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
@@ -4,13 +4,11 @@
4
4
  module PaperTrailDiff
5
5
  # Query pieces shared by version lookups.
6
6
  module VersionQuery
7
- module_function
8
-
9
7
  # Oldest first. Ids break ties between versions written in the same
10
8
  # instant, and the timestamp comes first because ids need not follow time:
11
9
  # a UUID key does not.
12
10
  #: (untyped) -> untyped
13
- def chronological(relation)
11
+ def self.chronological(relation)
14
12
  relation.reorder(created_at: :asc, id: :asc)
15
13
  end
16
14
 
@@ -19,13 +17,13 @@ module PaperTrailDiff
19
17
  # leave some out: a history replayed without them credits their changes to
20
18
  # the next version kept.
21
19
  #: (untyped) -> untyped
22
- def for_model(model_class)
20
+ def self.for_model(model_class)
23
21
  model_class.paper_trail.version_class.where(item_type: model_class.base_class.name)
24
22
  end
25
23
 
26
24
  # The versions of the given items, read the same way.
27
25
  #: (untyped, untyped) -> untyped
28
- def for_items(model_class, ids)
26
+ def self.for_items(model_class, ids)
29
27
  for_model(model_class).where(item_id: ids)
30
28
  end
31
29
 
@@ -33,33 +31,35 @@ module PaperTrailDiff
33
31
  # no other version of the same item that the block accepts is earlier. A
34
32
  # correlated NOT EXISTS stays portable where window functions are not.
35
33
  #: (untyped) ?{ (untyped) -> untyped } -> untyped
36
- def no_earlier_version(table, &block)
37
- no_nearer_version(table, later: true, &block)
34
+ def self.no_earlier_version(table, &block)
35
+ exists(table) { |other| earlier_version(table, other, &block) }.not
38
36
  end
39
37
 
40
- # The same for either side of an instant: each item's earliest version
41
- # when the versions lie after it, and its latest when they lie before.
42
- #: (untyped, later: bool) ?{ (untyped) -> untyped } -> untyped
43
- def no_nearer_version(table, later:, &block)
44
- arel = Object.const_get(:Arel) #: untyped
45
- other = table.alias('paper_trail_diff_earlier_versions')
46
- arel.const_get(:SelectManager).new
47
- .from(other)
48
- .project(arel.sql('1'))
49
- .where(nearer_version(table, other, later: later, &block))
50
- .exists
51
- .not
38
+ # Whether a version exists that the block's condition accepts. The block
39
+ # is given the version table under a second name, beside `table`.
40
+ #: (untyped) { (untyped) -> untyped } -> untyped
41
+ def self.exists(table)
42
+ other = other_versions(table)
43
+ Support.arel::SelectManager.new.from(other).project('1').where(yield(other)).exists
52
44
  end
53
45
 
54
- #: (untyped, untyped, later: bool) ?{ (untyped) -> untyped } -> untyped
55
- def nearer_version(table, other, later:)
56
- created_at = other[:created_at]
57
- nearer = later ? created_at.lt(table[:created_at]) : created_at.gt(table[:created_at])
46
+ #: (untyped, untyped) ?{ (untyped) -> untyped } -> untyped
47
+ def self.earlier_version(table, other)
58
48
  same_item = other[:item_type].eq(table[:item_type])
59
49
  .and(other[:item_id].eq(table[:item_id]))
60
- .and(nearer)
50
+ .and(other[:created_at].lt(table[:created_at]))
61
51
  block_given? ? same_item.and(yield(other)) : same_item
62
52
  end
63
- private_class_method :nearer_version
53
+ private_class_method :earlier_version
54
+
55
+ # The version table under a second name, for a subquery over it. Any name
56
+ # serves, and SQLite even accepts an empty one other databases refuse, so
57
+ # no spec can tell the mutations apart.
58
+ # mutant:disable
59
+ #: (untyped) -> untyped
60
+ def self.other_versions(table)
61
+ table.alias('paper_trail_diff_other_versions')
62
+ end
63
+ private_class_method :other_versions
64
64
  end
65
65
  end
@@ -13,12 +13,12 @@ module PaperTrailDiff
13
13
  end
14
14
 
15
15
  # Keep both reconstruction boundaries and the step pairs a filter implies.
16
- #: () -> RootVersionPlan
17
- def select_plan_for_range
16
+ #: (?whole: bool) -> RootVersionPlan
17
+ def select_plan_for_range(whole: false)
18
18
  relation = validated_relation
19
19
  select_plan(
20
20
  relation.where(created_at: @from.created_at..@to.created_at),
21
- through: @to
21
+ through: @to, whole: whole
22
22
  )
23
23
  end
24
24
 
@@ -34,12 +34,13 @@ module PaperTrailDiff
34
34
  relation
35
35
  end
36
36
 
37
- #: (untyped) -> RootVersionPlan
38
- def select_plan_through_current(current)
37
+ #: (untyped, ?whole: bool) -> RootVersionPlan
38
+ def select_plan_through_current(current, whole: false)
39
39
  Endpoint.validate_pair!(@record, current)
40
40
  relation = Endpoint.versions(@record)
41
41
  validate_boundary!(@from, relation, boundary: :from)
42
- select_plan(relation.where(created_at: @from.created_at..), live_endpoint: current)
42
+ select_plan(relation.where(created_at: @from.created_at..), live_endpoint: current,
43
+ whole: whole)
43
44
  end
44
45
 
45
46
  private
@@ -49,26 +50,21 @@ module PaperTrailDiff
49
50
  # @rbs @to: untyped
50
51
  # @rbs @version_scope: untyped
51
52
 
52
- #: (untyped, ?through: untyped, ?live_endpoint: untyped) -> RootVersionPlan
53
- def select_plan(relation, through: nil, live_endpoint: nil)
54
- in_range = ordered(relation.select do |version|
53
+ #: (untyped, whole: bool, ?through: untyped, ?live_endpoint: untyped) -> RootVersionPlan
54
+ def select_plan(relation, whole:, through: nil, live_endpoint: nil)
55
+ in_range = relation.select do |version|
55
56
  Support.compare_versions(@from, version) <= 0 &&
56
57
  (!through || Support.compare_versions(version, through) <= 0)
57
- end)
58
+ end
58
59
  RootVersionSelection.new(
59
60
  in_range: in_range,
60
61
  selected: VersionScopeFilter.new(@version_scope).call(relation, in_range),
61
62
  after_range: nil,
62
63
  windowed: false,
63
- filtered: !@version_scope.nil?, live_endpoint: live_endpoint
64
+ live_endpoint: live_endpoint, whole: whole
64
65
  ).call
65
66
  end
66
67
 
67
- #: (Array[untyped]) -> Array[untyped]
68
- def ordered(versions)
69
- Support.chronological_sort(versions)
70
- end
71
-
72
68
  #: (untyped, untyped, boundary: Symbol) -> void
73
69
  def validate_boundary!(requested, relation, boundary:)
74
70
  return if valid_boundary?(requested, relation)
@@ -13,11 +13,15 @@ module PaperTrailDiff
13
13
  @fallback_selected = fallback_selected
14
14
  end
15
15
 
16
+ # The read runs in a savepoint, so that a query that fails here leaves a
17
+ # snapshot transaction around it usable: PostgreSQL refuses every later
18
+ # statement of a transaction once one has failed.
16
19
  #: () -> Array[DiagnosticIssue]
17
20
  def call
18
- versions = ordered_range_versions
21
+ versions = @from_version.class.transaction(requires_new: true) { ordered_range_versions }
19
22
  issues = [] #: Array[DiagnosticIssue?]
20
23
  issues << unorderable(versions)
24
+ issues << inverted(versions)
21
25
  issues << tied_timestamps(versions) if @fallback_selected
22
26
  issues.compact
23
27
  rescue StandardError
@@ -46,6 +50,37 @@ module PaperTrailDiff
46
50
  )
47
51
  end
48
52
 
53
+ # Versions are read in time order, and ids that count up in one table say
54
+ # which was saved first. A later version dated earlier was usually dated
55
+ # by PaperTrail at an `updated_at` the application set itself, and the
56
+ # history then reads it before the change it followed: an update dated
57
+ # before the record's create reads as the record deleted and created
58
+ # again. A time can also be right and the id wrong, as for versions
59
+ # imported from elsewhere, so this warns rather than refuses.
60
+ #: (Array[untyped]) -> DiagnosticIssue?
61
+ def inverted(versions)
62
+ pair = versions.each_cons(2).find do |left, right|
63
+ Support.orderable_tie?(left, right) && Integer(right.id) < Integer(left.id)
64
+ end
65
+ return unless pair
66
+
67
+ saved_last, saved_first = pair
68
+ DiagnosticIssue.new(
69
+ severity: :warning, code: :inverted_version_order,
70
+ message: inverted_message(saved_first, saved_last), version_id: saved_last.id
71
+ )
72
+ end
73
+
74
+ #: (untyped, untyped) -> String
75
+ def inverted_message(saved_first, saved_last)
76
+ "versions #{saved_first.id.inspect} and #{saved_last.id.inspect} were saved in that " \
77
+ 'order but are dated the other way round, at ' \
78
+ "#{saved_first.created_at.inspect} and #{saved_last.created_at.inspect}, and history " \
79
+ 'reads them in time order; if a save set updated_at itself, which PaperTrail then ' \
80
+ 'dates its version at, set has_paper_trail synchronize_version_creation_timestamp: ' \
81
+ 'false and correct the stored created_at'
82
+ end
83
+
49
84
  # Loaded history orders versions that share a timestamp by id, but PT-AT
50
85
  # places association changes by timestamp alone, so a path it reads loses
51
86
  # any change between such a pair. Unlike an unorderable sequence this is
@@ -25,20 +25,24 @@ module PaperTrailDiff
25
25
  # and an unversioned target has no history to compare.
26
26
  #: (untyped) -> untyped
27
27
  def self.separate_part(reflection)
28
- if reflection.through_reflection?
29
- return [reflection.through_reflection, reflection.source_reflection].filter_map do |part|
30
- separate_part(part)
31
- end.first
28
+ [reflection, *AssociationTraversal.through_parts(reflection)].find do |part|
29
+ !part.through_reflection? && separate?(part)
32
30
  end
33
- return if reflection.polymorphic?
31
+ end
32
+ private_class_method :separate_part
33
+
34
+ #: (untyped) -> bool
35
+ def self.separate?(reflection)
36
+ return false if reflection.polymorphic?
34
37
 
35
38
  owner = reflection.active_record
36
39
  target = reflection.klass
37
- return unless Support.versioned?(owner) && Support.versioned?(target)
40
+ return false unless Support.versioned?(owner) && Support.versioned?(target)
41
+ return false if tables(owner) == tables(target)
38
42
 
39
- reflection unless tables(owner) == tables(target)
43
+ true
40
44
  end
41
- private_class_method :separate_part
45
+ private_class_method :separate?
42
46
 
43
47
  # PT-AT's version association rows joined to the versions they were saved
44
48
  # with. Its `belongs_to :version` names PaperTrail's default class whatever
@@ -7,6 +7,9 @@ require_relative 'paper_trail_diff/version'
7
7
  require_relative 'paper_trail_diff/support'
8
8
  require_relative 'paper_trail_diff/version_query'
9
9
  require_relative 'paper_trail_diff/stored_time_precision'
10
+ require_relative 'paper_trail_diff/stored_json_values'
11
+ require_relative 'paper_trail_diff/time_of_day'
12
+ require_relative 'paper_trail_diff/stored_values'
10
13
  require_relative 'paper_trail_diff/version_boundary'
11
14
  require_relative 'paper_trail_diff/instrumentation'
12
15
  require_relative 'paper_trail_diff/deprecation'
@@ -53,7 +56,6 @@ require_relative 'paper_trail_diff/prepared_association_reifier'
53
56
  require_relative 'paper_trail_diff/live_association_reader'
54
57
  require_relative 'paper_trail_diff/batch_preload'
55
58
  require_relative 'paper_trail_diff/live_endpoint_batch_loader'
56
- require_relative 'paper_trail_diff/preloaded_endpoint_batch_loader'
57
59
  require_relative 'paper_trail_diff/live_endpoint_provider'
58
60
  require_relative 'paper_trail_diff/live_graph_collector'
59
61
  require_relative 'paper_trail_diff/batch_boundary_resolver'
@@ -61,12 +63,14 @@ require_relative 'paper_trail_diff/comparison_batch'
61
63
  require_relative 'paper_trail_diff/root_version_plan'
62
64
  require_relative 'paper_trail_diff/version_scope_filter'
63
65
  require_relative 'paper_trail_diff/root_version_selection'
66
+ require_relative 'paper_trail_diff/own_window'
64
67
  require_relative 'paper_trail_diff/batched_root_versions'
65
68
  require_relative 'paper_trail_diff/snapshot_normalizer'
66
69
  require_relative 'paper_trail_diff/historical_snapshot_store'
67
70
  require_relative 'paper_trail_diff/timeline_snapshot_provider'
68
71
  require_relative 'paper_trail_diff/activity_event_record_resolver'
69
72
  require_relative 'paper_trail_diff/recorded_changes'
73
+ require_relative 'paper_trail_diff/recorded_changes_reader'
70
74
  require_relative 'paper_trail_diff/activity_event_route_finder'
71
75
  require_relative 'paper_trail_diff/activity_relationship'
72
76
  require_relative 'paper_trail_diff/activity_collection_route_change'
@@ -79,17 +83,23 @@ require_relative 'paper_trail_diff/activity_event_snapshot_refresher'
79
83
  require_relative 'paper_trail_diff/activity_root_snapshot_refresher'
80
84
  require_relative 'paper_trail_diff/branch_snapshot_refresher'
81
85
  require_relative 'paper_trail_diff/activity_boundary'
86
+ require_relative 'paper_trail_diff/recorded_columns'
87
+ require_relative 'paper_trail_diff/change_attribution'
88
+ require_relative 'paper_trail_diff/activity_scope_filter'
82
89
  require_relative 'paper_trail_diff/activity_view'
83
90
  require_relative 'paper_trail_diff/activity_transaction_grouper'
91
+ require_relative 'paper_trail_diff/net_change'
84
92
  require_relative 'paper_trail_diff/step'
85
93
  require_relative 'paper_trail_diff/analysis'
86
94
  require_relative 'paper_trail_diff/activity_root_steps'
95
+ require_relative 'paper_trail_diff/batched_root_analyses'
87
96
  require_relative 'paper_trail_diff/analysis_batch'
88
97
  require_relative 'paper_trail_diff/deleted_analysis_batch'
89
98
  require_relative 'paper_trail_diff/scoped_analysis'
90
99
  require_relative 'paper_trail_diff/historical_filter'
91
100
  require_relative 'paper_trail_diff/association_activity_edge'
92
101
  require_relative 'paper_trail_diff/association_activity_selection'
102
+ require_relative 'paper_trail_diff/total_order'
93
103
  require_relative 'paper_trail_diff/scoped_root_selection'
94
104
  require_relative 'paper_trail_diff/deleted_root_filter'
95
105
  require_relative 'paper_trail_diff/scoped_analysis_builder'
@@ -104,12 +114,14 @@ require_relative 'paper_trail_diff/timeline_builder'
104
114
  require_relative 'paper_trail_diff/activity_range'
105
115
  require_relative 'paper_trail_diff/activity_event'
106
116
  require_relative 'paper_trail_diff/activity_child_candidate_loader'
117
+ require_relative 'paper_trail_diff/prepared_child_candidates'
107
118
  require_relative 'paper_trail_diff/activity_target_candidate_loader'
108
119
  require_relative 'paper_trail_diff/activity_version_collector'
109
120
  require_relative 'paper_trail_diff/activity_snapshot_sequence'
110
121
  require_relative 'paper_trail_diff/activity_tree_filter'
111
122
  require_relative 'paper_trail_diff/activity_history'
112
123
  require_relative 'paper_trail_diff/activity_timeline_builder'
124
+ require_relative 'paper_trail_diff/read_snapshot'
113
125
  require_relative 'paper_trail_diff/paper_trail_adapter'
114
126
 
115
127
  # @rbs!
@@ -150,45 +162,35 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
150
162
 
151
163
  class << self # rubocop:disable Metrics/ClassLength
152
164
  # Compares net state between explicit PaperTrail-version or current-record endpoints.
153
- #: (untyped, untyped, ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?allow_approximate: bool) -> Diff
154
- def compare( # rubocop:disable Metrics/ParameterLists
165
+ #: (untyped, untyped, ?associations: association_option, ?ignore: ignore_option, ?allow_approximate: bool) -> Diff
166
+ def compare(
155
167
  from_version,
156
168
  to_version,
157
169
  associations: [],
158
170
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
159
- reload_live_endpoints: nil,
160
171
  allow_approximate: false
161
172
  )
162
173
  PaperTrailAdapter.new(
163
- associations: associations,
164
- ignore: ignore,
165
- reload_live_endpoints: Deprecation.reload_live_endpoints!(reload_live_endpoints),
166
- allow_approximate: allow_approximate
174
+ associations: associations, ignore: ignore, allow_approximate: allow_approximate
167
175
  ).compare(from_version, to_version)
168
176
  end
169
177
 
170
178
  # Compares many independent endpoint pairs while batching current-record loading.
171
- #: (Array[comparison_input], ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?allow_expensive: bool?, ?allow_approximate: bool) -> comparison_results
172
- def compare_many( # rubocop:disable Metrics/ParameterLists
179
+ #: (Array[comparison_input], ?associations: association_option, ?ignore: ignore_option, ?allow_approximate: bool) -> comparison_results
180
+ def compare_many(
173
181
  comparisons,
174
182
  associations: [],
175
183
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
176
- reload_live_endpoints: nil,
177
- allow_expensive: nil,
178
184
  allow_approximate: false
179
185
  )
180
- Deprecation.allow_expensive!(allow_expensive)
181
186
  PaperTrailAdapter.new(
182
- associations: associations,
183
- ignore: ignore,
184
- reload_live_endpoints: Deprecation.reload_live_endpoints!(reload_live_endpoints),
185
- allow_approximate: allow_approximate
187
+ associations: associations, ignore: ignore, allow_approximate: allow_approximate
186
188
  ).compare_many(comparisons)
187
189
  end
188
190
 
189
191
  # Compares every adjacent reconstructed state in an inclusive version range,
190
192
  # by default the record's whole history through its current state.
191
- #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?close_on: Symbol?, ?allow_approximate: bool) -> Array[Step]
193
+ #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?allow_approximate: bool) -> Array[Step]
192
194
  def timeline( # rubocop:disable Metrics/ParameterLists
193
195
  record,
194
196
  from: nil,
@@ -197,10 +199,8 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
197
199
  associations: [],
198
200
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
199
201
  version_scope: nil,
200
- close_on: nil,
201
202
  allow_approximate: false
202
203
  )
203
- Deprecation.close_on!(close_on, within)
204
204
  PaperTrailAdapter.new(
205
205
  associations: associations, ignore: ignore, allow_approximate: allow_approximate
206
206
  ).timeline(
@@ -213,7 +213,7 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
213
213
  end
214
214
 
215
215
  # Compares adjacent root and selected-descendant activity boundaries.
216
- #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Array[ActivityStep]
216
+ #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Array[ActivityStep]
217
217
  def activity_timeline( # rubocop:disable Metrics/ParameterLists
218
218
  record,
219
219
  from: nil,
@@ -221,18 +221,14 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
221
221
  within: nil,
222
222
  associations: [],
223
223
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
224
- reload_live_endpoints: nil,
225
224
  version_scope: nil,
226
- close_on: nil,
227
225
  snapshots: false,
228
226
  group: nil,
229
227
  recorded_changes: false,
230
228
  allow_approximate: false
231
229
  )
232
- Deprecation.close_on!(close_on, within)
233
230
  PaperTrailAdapter.new(
234
231
  associations: associations, ignore: ignore,
235
- reload_live_endpoints: Deprecation.reload_live_endpoints!(reload_live_endpoints),
236
232
  recorded_changes: recorded_changes, allow_approximate: allow_approximate
237
233
  ).activity_timeline(
238
234
  record,
@@ -246,7 +242,7 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
246
242
  end
247
243
 
248
244
  # Builds an endpoint diff and root-checkpoint timeline while normalizing each version once.
249
- #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Analysis
245
+ #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Analysis
250
246
  def analyze( # rubocop:disable Metrics/ParameterLists
251
247
  record,
252
248
  from: nil,
@@ -256,13 +252,11 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
256
252
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
257
253
  activity: false,
258
254
  version_scope: nil,
259
- close_on: nil,
260
255
  snapshots: false,
261
256
  group: nil,
262
257
  recorded_changes: false,
263
258
  allow_approximate: false
264
259
  )
265
- Deprecation.close_on!(close_on, within)
266
260
  PaperTrailAdapter.new(
267
261
  associations: associations, ignore: ignore, recorded_changes: recorded_changes,
268
262
  allow_approximate: allow_approximate
@@ -283,7 +277,7 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
283
277
  # returns a frozen Hash keyed by identity. Roots with nothing to report in
284
278
  # the window return an empty `Analysis`. To let a relation choose the
285
279
  # records, use `analyze_scope`.
286
- #: (Array[untyped], ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> Hash[identity, Analysis]
280
+ #: (Array[untyped], ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Hash[identity, Analysis]
287
281
  def analyze_many( # rubocop:disable Metrics/ParameterLists
288
282
  records,
289
283
  within: nil,
@@ -291,15 +285,11 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
291
285
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
292
286
  activity: false,
293
287
  version_scope: nil,
294
- close_on: nil,
295
288
  snapshots: false,
296
289
  group: nil,
297
- allow_expensive: nil,
298
290
  recorded_changes: false,
299
291
  allow_approximate: false
300
292
  )
301
- Deprecation.close_on!(close_on, within)
302
- Deprecation.allow_expensive!(allow_expensive)
303
293
  PaperTrailAdapter.new(
304
294
  associations: associations, ignore: ignore,
305
295
  recorded_changes: recorded_changes, allow_approximate: allow_approximate
@@ -333,7 +323,7 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
333
323
  # Note also that a relation selects on current state, not on state during
334
324
  # the window: `where(status: 'published')` means published *now*, which is a
335
325
  # different set from what was published while the window was open.
336
- #: (untyped, limit: Integer?, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
326
+ #: (untyped, limit: Integer?, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
337
327
  def analyze_scope( # rubocop:disable Metrics/ParameterLists
338
328
  scope,
339
329
  limit:,
@@ -342,18 +332,14 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
342
332
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
343
333
  activity: false,
344
334
  version_scope: nil,
345
- close_on: nil,
346
335
  snapshots: false,
347
336
  group: nil,
348
337
  historical_filter: nil,
349
338
  max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT,
350
339
  include_deleted: false,
351
- allow_expensive: nil,
352
340
  recorded_changes: false,
353
341
  allow_approximate: false
354
342
  )
355
- Deprecation.close_on!(close_on, within)
356
- Deprecation.allow_expensive!(allow_expensive)
357
343
  adapter = PaperTrailAdapter.new(associations: associations, ignore: ignore,
358
344
  recorded_changes: recorded_changes,
359
345
  allow_approximate: allow_approximate)
@@ -369,11 +355,11 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
369
355
  # for every root that changed or whose requested associations did.
370
356
  # Historical windows remain explicit on analyze_scope; this entry point is
371
357
  # deliberately named for a report through now rather than an as-of query.
372
- #: (untyped, since: untyped, limit: Integer, ?associations: association_option, ?ignore: ignore_option, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
358
+ #: (untyped, since: untyped, limit: Integer, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
373
359
  def report( # rubocop:disable Metrics/ParameterLists
374
360
  scope, since:, limit:, associations: [], ignore: DEFAULT_IGNORED_ATTRIBUTES,
375
- snapshots: false, group: nil, include_deleted: false, historical_filter: nil,
376
- max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, allow_expensive: nil,
361
+ version_scope: nil, snapshots: false, group: nil, include_deleted: false,
362
+ historical_filter: nil, max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT,
377
363
  recorded_changes: false, allow_approximate: false
378
364
  )
379
365
  # A range here would become the start of another range.
@@ -382,12 +368,14 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
382
368
  'pass it as `within:` to analyze_scope'
383
369
  end
384
370
 
371
+ # Endless, so a version a server dated ahead of this one's clock is in it.
385
372
  analyze_scope(
386
373
  scope,
387
- within: since..Time.now.utc, limit: limit, associations: associations,
388
- ignore: ignore, activity: true, snapshots: snapshots, group: group,
374
+ within: (since..), limit: limit, associations: associations,
375
+ ignore: ignore, activity: true, version_scope: version_scope, snapshots: snapshots,
376
+ group: group,
389
377
  include_deleted: include_deleted, historical_filter: historical_filter,
390
- max_filter_versions: max_filter_versions, allow_expensive: allow_expensive,
378
+ max_filter_versions: max_filter_versions,
391
379
  recorded_changes: recorded_changes, allow_approximate: allow_approximate
392
380
  )
393
381
  end
@@ -17,11 +17,6 @@ module PaperTrailDiff
17
17
 
18
18
  @route_finder: ActivityEventRouteFinder
19
19
 
20
- # An edit can move a target into or out of a scope, which a replacement
21
- # in place cannot show, so a scoped route's branch is read again instead.
22
- # : (Array[Array[untyped]]) -> bool
23
- def scoped_route?: (Array[Array[untyped]]) -> bool
24
-
25
20
  # : (Array[untyped], untyped, SnapshotNormalizer, untyped, untyped) -> RecordSnapshot?
26
21
  def normalized_route_record: (Array[untyped], untyped, SnapshotNormalizer, untyped, untyped) -> RecordSnapshot?
27
22
 
@@ -39,8 +34,5 @@ module PaperTrailDiff
39
34
  # row whose type changes is replaced by a record of another class.
40
35
  # : (RecordSnapshot, untyped) -> bool
41
36
  def same_table?: (RecordSnapshot, untyped) -> bool
42
-
43
- # : (untyped) -> untyped
44
- def endpoint_model_class: (untyped) -> untyped
45
37
  end
46
38
  end
@@ -32,27 +32,37 @@ module PaperTrailDiff
32
32
 
33
33
  NOT_READ_MESSAGE: ::String
34
34
 
35
- # `recorded:` names the attributes to leave out of the version's recorded
36
- # changes, or is nil when they were not asked for. Reading them decodes
37
- # `object_changes`, which a caller who does not want them should not pay.
38
- # : (untyped, ?recorded: Array[String]?) -> ActivityBoundary
39
- def self.from_version: (untyped, ?recorded: Array[String]?) -> ActivityBoundary
35
+ # `recorded:` reads the version's recorded changes, or is nil when they
36
+ # were not asked for. Reading them decodes `object_changes`, which waits
37
+ # until a caller reads them, and which one who never does should not pay.
38
+ # : (untyped, ?recorded: RecordedChangesReader?) -> ActivityBoundary
39
+ def self.from_version: (untyped, ?recorded: RecordedChangesReader?) -> ActivityBoundary
40
40
 
41
41
  # The current record has no version, so it recorded nothing.
42
- # : (untyped, captured_at: untyped, ?recorded: Array[String]?) -> ActivityBoundary
43
- def self.current: (untyped, captured_at: untyped, ?recorded: Array[String]?) -> ActivityBoundary
42
+ # : (untyped, captured_at: untyped, ?recorded: RecordedChangesReader?) -> ActivityBoundary
43
+ def self.current: (untyped, captured_at: untyped, ?recorded: RecordedChangesReader?) -> ActivityBoundary
44
44
 
45
45
  # The state a `destroy` version leaves behind. A version records the state
46
46
  # before its own event, so the boundary built from a destroy version still
47
47
  # holds the record; this one is the absence that follows it.
48
- # : (untyped, ?recorded: Array[String]?) -> ActivityBoundary
49
- def self.destroyed: (untyped, ?recorded: Array[String]?) -> ActivityBoundary
48
+ # : (untyped, ?recorded: RecordedChangesReader?) -> ActivityBoundary
49
+ def self.destroyed: (untyped, ?recorded: RecordedChangesReader?) -> ActivityBoundary
50
50
 
51
- # : (untyped, Array[String]?) -> untyped
52
- private def self.recorded_changes: (untyped, Array[String]?) -> untyped
51
+ # Where a change saved without a version came from, such as an
52
+ # `update_columns` call: no version, event, author or time recorded it,
53
+ # so it has none to report. A change row names it as its source.
54
+ # : (item_type: String, item_id: untyped) -> ActivityBoundary
55
+ def self.unversioned: (item_type: String, item_id: untyped) -> ActivityBoundary
56
+
57
+ # : (untyped, Symbol, RecordedChangesReader?) -> ActivityBoundary
58
+ private def self.of_version: (untyped, Symbol, RecordedChangesReader?) -> ActivityBoundary
59
+
60
+ # : (untyped, RecordedChangesReader?) -> untyped
61
+ private def self.recorded_changes: (untyped, RecordedChangesReader?) -> untyped
53
62
 
54
63
  # `recorded_changes:` takes what `PaperTrailDiff.recorded_changes` returns
55
- # for the version; leave it out when they were not read.
64
+ # for the version, or a RecordedChangesReader::Pending that reads it when
65
+ # first asked; leave it out when they were not read.
56
66
  # : (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped, ?transaction_id: untyped, ?recorded_changes: untyped) -> void
57
67
  def initialize: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped, ?transaction_id: untyped, ?recorded_changes: untyped) -> void
58
68
 
@@ -77,6 +87,9 @@ module PaperTrailDiff
77
87
  # : () -> bool
78
88
  def destroyed?: () -> bool
79
89
 
90
+ # : () -> bool
91
+ def unversioned?: () -> bool
92
+
80
93
  # : (?metadata: bool) -> Hash[Symbol, untyped]
81
94
  def to_h: (?metadata: bool) -> Hash[Symbol, untyped]
82
95
  end
@@ -104,14 +117,21 @@ module PaperTrailDiff
104
117
  # would credit the rest of the save to whoever opened it.
105
118
  attr_reader sources: Array[ActivityBoundary]
106
119
 
120
+ # @api private
121
+ # What credits this step's change rows, which a transaction group extends
122
+ # over the steps it merges.
123
+ attr_reader attribution: ChangeAttribution?
124
+
107
125
  # Compares two reconstructed states and keeps them only when asked, which is
108
126
  # every caller's shape: the diff always comes from the pair, the pair itself
109
127
  # is retained on request.
110
- # : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool, ?sources: Array[ActivityBoundary]?) -> ActivityStep
111
- def self.between: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool, ?sources: Array[ActivityBoundary]?) -> ActivityStep
128
+ # : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool, ?sources: Array[ActivityBoundary]?, ?attribution: ChangeAttribution?) -> ActivityStep
129
+ def self.between: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool, ?sources: Array[ActivityBoundary]?, ?attribution: ChangeAttribution?) -> ActivityStep
112
130
 
113
- # : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?sources: Array[ActivityBoundary]?) -> void
114
- def initialize: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?sources: Array[ActivityBoundary]?) -> void
131
+ # `attribution` credits each change row to the version that made it (see
132
+ # ChangeAttribution); without it, every row names `source_boundary`.
133
+ # : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?sources: Array[ActivityBoundary]?, ?attribution: ChangeAttribution?) -> void
134
+ def initialize: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?sources: Array[ActivityBoundary]?, ?attribution: ChangeAttribution?) -> void
115
135
 
116
136
  # : () -> bool
117
137
  def empty?: () -> bool
@@ -121,7 +141,9 @@ module PaperTrailDiff
121
141
  # : () -> ActivityBoundary
122
142
  def source_boundary: () -> ActivityBoundary
123
143
 
124
- # The diff as flat rows, each attributed to `source_boundary`.
144
+ # The diff as flat rows, each credited to the event that made its change:
145
+ # the version of the row's record that recorded it, an unversioned source
146
+ # for a part saved without a version, or else `source_boundary`.
125
147
  # : () -> Array[ChangeRow]
126
148
  def change_rows: () -> Array[ChangeRow]
127
149