paper_trail_diff 0.13.1 → 0.15.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 (181) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +630 -0
  3. data/QUICKSTART.md +30 -10
  4. data/README.md +91 -13
  5. data/docs/architecture.md +62 -18
  6. data/docs/performance.md +116 -298
  7. data/docs/reference.md +554 -102
  8. data/docs/testing.md +93 -14
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +19 -9
  10. data/lib/paper_trail_diff/activity_boundary.rb +83 -26
  11. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
  12. data/lib/paper_trail_diff/activity_collection_event_applier.rb +11 -1
  13. data/lib/paper_trail_diff/activity_collection_record_updater.rb +16 -2
  14. data/lib/paper_trail_diff/activity_event.rb +41 -10
  15. data/lib/paper_trail_diff/activity_event_record_resolver.rb +20 -1
  16. data/lib/paper_trail_diff/activity_event_route_finder.rb +2 -1
  17. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +1 -1
  18. data/lib/paper_trail_diff/activity_history.rb +34 -9
  19. data/lib/paper_trail_diff/activity_range.rb +32 -5
  20. data/lib/paper_trail_diff/activity_relationship.rb +12 -0
  21. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +5 -2
  22. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
  23. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +131 -0
  24. data/lib/paper_trail_diff/activity_timeline_builder.rb +281 -120
  25. data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
  26. data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
  27. data/lib/paper_trail_diff/activity_version_collector.rb +37 -24
  28. data/lib/paper_trail_diff/activity_view.rb +69 -0
  29. data/lib/paper_trail_diff/analysis.rb +13 -1
  30. data/lib/paper_trail_diff/analysis_batch.rb +24 -30
  31. data/lib/paper_trail_diff/approximate_paths.rb +48 -0
  32. data/lib/paper_trail_diff/association_activity_edge.rb +236 -0
  33. data/lib/paper_trail_diff/association_activity_selection.rb +197 -0
  34. data/lib/paper_trail_diff/association_discovery.rb +14 -11
  35. data/lib/paper_trail_diff/association_key.rb +56 -0
  36. data/lib/paper_trail_diff/association_traversal.rb +180 -47
  37. data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
  38. data/lib/paper_trail_diff/batch_preload.rb +53 -0
  39. data/lib/paper_trail_diff/batched_root_analyzer.rb +12 -14
  40. data/lib/paper_trail_diff/batched_root_versions.rb +53 -47
  41. data/lib/paper_trail_diff/change_row.rb +133 -0
  42. data/lib/paper_trail_diff/collection_comparator.rb +5 -32
  43. data/lib/paper_trail_diff/comparison_batch.rb +37 -10
  44. data/lib/paper_trail_diff/configuration.rb +35 -12
  45. data/lib/paper_trail_diff/deleted_analysis_batch.rb +45 -27
  46. data/lib/paper_trail_diff/deleted_root_filter.rb +79 -0
  47. data/lib/paper_trail_diff/deprecation.rb +61 -0
  48. data/lib/paper_trail_diff/diagnostics.rb +105 -102
  49. data/lib/paper_trail_diff/direct_record_state_loader.rb +10 -1
  50. data/lib/paper_trail_diff/endpoint.rb +26 -3
  51. data/lib/paper_trail_diff/errors.rb +5 -2
  52. data/lib/paper_trail_diff/fallback_paths.rb +38 -0
  53. data/lib/paper_trail_diff/habtm_transaction_owners.rb +68 -0
  54. data/lib/paper_trail_diff/historical_association_reifier.rb +34 -6
  55. data/lib/paper_trail_diff/historical_filter.rb +19 -10
  56. data/lib/paper_trail_diff/historical_snapshot_store.rb +63 -76
  57. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +12 -13
  58. data/lib/paper_trail_diff/live_graph_collector.rb +1 -1
  59. data/lib/paper_trail_diff/nested_comparator.rb +19 -18
  60. data/lib/paper_trail_diff/paper_trail_adapter.rb +136 -125
  61. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +14 -2
  62. data/lib/paper_trail_diff/prepared_activity_index.rb +110 -36
  63. data/lib/paper_trail_diff/prepared_edge_loader.rb +31 -46
  64. data/lib/paper_trail_diff/prepared_history.rb +70 -53
  65. data/lib/paper_trail_diff/prepared_history_loader.rb +34 -43
  66. data/lib/paper_trail_diff/prepared_record_index.rb +64 -7
  67. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +1 -1
  68. data/lib/paper_trail_diff/prepared_state_association_reader.rb +119 -29
  69. data/lib/paper_trail_diff/recorded_changes.rb +83 -0
  70. data/lib/paper_trail_diff/recorded_class.rb +53 -0
  71. data/lib/paper_trail_diff/root_version_selection.rb +4 -2
  72. data/lib/paper_trail_diff/scope_condition.rb +386 -0
  73. data/lib/paper_trail_diff/scope_ranking.rb +206 -0
  74. data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
  75. data/lib/paper_trail_diff/scoped_analysis_builder.rb +20 -11
  76. data/lib/paper_trail_diff/scoped_root_selection.rb +105 -49
  77. data/lib/paper_trail_diff/snapshot.rb +16 -1
  78. data/lib/paper_trail_diff/snapshot_normalizer.rb +10 -3
  79. data/lib/paper_trail_diff/support.rb +38 -6
  80. data/lib/paper_trail_diff/time_range.rb +37 -18
  81. data/lib/paper_trail_diff/time_version_range.rb +5 -5
  82. data/lib/paper_trail_diff/timeline_builder.rb +7 -7
  83. data/lib/paper_trail_diff/timeline_range.rb +9 -1
  84. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
  85. data/lib/paper_trail_diff/transaction_cut.rb +181 -0
  86. data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
  87. data/lib/paper_trail_diff/version.rb +1 -1
  88. data/lib/paper_trail_diff/version_association_candidate_scope.rb +13 -3
  89. data/lib/paper_trail_diff/version_boundary.rb +37 -8
  90. data/lib/paper_trail_diff/version_query.rb +34 -10
  91. data/lib/paper_trail_diff/version_range.rb +8 -15
  92. data/lib/paper_trail_diff/version_scope_filter.rb +20 -13
  93. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +31 -16
  94. data/lib/paper_trail_diff/version_table.rb +60 -0
  95. data/lib/paper_trail_diff.rb +126 -55
  96. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +10 -2
  97. data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
  98. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +5 -0
  99. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +5 -0
  100. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
  101. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +7 -0
  102. data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
  103. data/sig/generated/paper_trail_diff/activity_range.rbs +14 -3
  104. data/sig/generated/paper_trail_diff/activity_relationship.rbs +3 -0
  105. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +2 -0
  106. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
  107. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +79 -0
  108. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -28
  109. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
  110. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +12 -4
  111. data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
  112. data/sig/generated/paper_trail_diff/analysis.rbs +8 -1
  113. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
  114. data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
  115. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +148 -0
  116. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +112 -0
  117. data/sig/generated/paper_trail_diff/association_discovery.rbs +8 -5
  118. data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
  119. data/sig/generated/paper_trail_diff/association_traversal.rbs +88 -9
  120. data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
  121. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -10
  122. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -10
  123. data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
  124. data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
  125. data/sig/generated/paper_trail_diff/comparison_batch.rbs +22 -4
  126. data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
  127. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +20 -8
  128. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +48 -0
  129. data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
  130. data/sig/generated/paper_trail_diff/diagnostics.rbs +44 -32
  131. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +6 -0
  132. data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
  133. data/sig/generated/paper_trail_diff/errors.rbs +5 -2
  134. data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
  135. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +40 -0
  136. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +13 -0
  137. data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
  138. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +36 -30
  139. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +5 -3
  140. data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
  141. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +55 -48
  142. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
  143. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +52 -10
  144. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -12
  145. data/sig/generated/paper_trail_diff/prepared_history.rbs +40 -24
  146. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +15 -13
  147. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +34 -2
  148. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +56 -11
  149. data/sig/generated/paper_trail_diff/recorded_changes.rbs +47 -0
  150. data/sig/generated/paper_trail_diff/recorded_class.rbs +22 -0
  151. data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
  152. data/sig/generated/paper_trail_diff/scope_condition.rbs +219 -0
  153. data/sig/generated/paper_trail_diff/scope_ranking.rbs +125 -0
  154. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
  155. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +8 -3
  156. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -11
  157. data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
  158. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +6 -0
  159. data/sig/generated/paper_trail_diff/support.rbs +20 -2
  160. data/sig/generated/paper_trail_diff/time_range.rbs +20 -2
  161. data/sig/generated/paper_trail_diff/time_version_range.rbs +4 -4
  162. data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -2
  163. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
  164. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
  165. data/sig/generated/paper_trail_diff/transaction_cut.rbs +94 -0
  166. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
  167. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +7 -0
  168. data/sig/generated/paper_trail_diff/version_boundary.rbs +20 -3
  169. data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
  170. data/sig/generated/paper_trail_diff/version_range.rbs +4 -2
  171. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +7 -4
  172. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -9
  173. data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
  174. data/sig/generated/paper_trail_diff.rbs +47 -25
  175. metadata +62 -10
  176. data/lib/paper_trail_diff/activity_grouping.rb +0 -38
  177. data/lib/paper_trail_diff/batch_safety.rb +0 -55
  178. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -224
  179. data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
  180. data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -24
  181. data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
@@ -5,22 +5,22 @@ module PaperTrailDiff
5
5
  # Builds one root's Analysis inside a batch, from versions the batch already
6
6
  # selected and history it already prepared.
7
7
  class BatchedRootAnalyzer
8
- #: (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool, ?within: untyped, ?snapshots: bool, ?group: Symbol?) -> void
9
- def initialize(tree:, timeline_snapshotter:, activity_snapshotter:, preparer:, activity:, within: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
8
+ #: (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool, view: ActivityView, ?within: untyped) -> void
9
+ def initialize(tree:, timeline_snapshotter:, activity_snapshotter:, preparer:, activity:, view:, within: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
10
10
  @tree = tree
11
11
  @timeline_snapshotter = timeline_snapshotter
12
12
  @activity_snapshotter = activity_snapshotter
13
13
  @preparer = preparer
14
14
  @activity = activity
15
+ @view = view
15
16
  @within = within
16
- @snapshots = snapshots
17
- @group = group
18
17
  end
19
18
 
20
- #: (untyped, RootVersionPlan) -> Analysis
21
- def call(record, plan)
19
+ # `window` is the root's window as the batch moved it to transaction edges.
20
+ #: (untyped, RootVersionPlan, ?TimeRange?) -> Analysis
21
+ def call(record, plan, window = nil)
22
22
  @preparer.call(record.class, historical: true)
23
- return activity_analysis(record, plan) if @activity
23
+ return activity_analysis(record, plan, window) if @activity
24
24
 
25
25
  TimelineBuilder.new(
26
26
  record,
@@ -40,19 +40,17 @@ module PaperTrailDiff
40
40
  # @rbs @preparer: untyped
41
41
  # @rbs @activity: bool
42
42
  # @rbs @within: untyped
43
- # @rbs @snapshots: bool
44
- # @rbs @group: Symbol?
43
+ # @rbs @view: ActivityView
45
44
 
46
- #: (untyped, RootVersionPlan) -> Analysis
47
- def activity_analysis(record, plan)
45
+ #: (untyped, RootVersionPlan, TimeRange?) -> Analysis
46
+ def activity_analysis(record, plan, window)
48
47
  range = TimelineRange.new(
49
48
  record, from: (@within ? nil : plan.versions.first),
50
49
  to: (@within ? nil : plan.closing_record || plan.versions.last),
51
- within: @within, plan: plan
50
+ within: (window || @within if @within), plan: plan
52
51
  )
53
52
  ActivityTimelineBuilder.new(
54
- record, range: range, tree: @tree, snapshotter: @activity_snapshotter,
55
- snapshots: @snapshots, group: @group
53
+ record, range: range, tree: @tree, snapshotter: @activity_snapshotter, view: @view
56
54
  ).analyze
57
55
  end
58
56
  end
@@ -6,10 +6,13 @@ module PaperTrailDiff
6
6
  # queries. Only the range forms that mean the same thing for every root are
7
7
  # supported: a shared wall-clock window, or each root's own whole history.
8
8
  class BatchedRootVersions
9
- #: (Array[untyped], time_range: TimeRange?, ?version_scope: untyped, ?live_endpoints: Hash[Array[String], untyped]?, ?context_required: bool) -> void
10
- def initialize(records, time_range:, version_scope: nil, live_endpoints: nil,
11
- context_required: false)
9
+ #: (Array[untyped], time_range: TimeRange?, version_scope: untyped, live_endpoints: Hash[Array[String], untyped]?, context_required: bool, windows: Hash[Array[String], TimeRange]) -> void
10
+ def initialize( # rubocop:disable Metrics/ParameterLists
11
+ records, time_range:, version_scope:, live_endpoints:, context_required:, windows:
12
+ )
12
13
  @records = records
14
+ # Roots whose window moved to a transaction's start, by identity.
15
+ @windows = windows
13
16
  # An activity view needs a root to reconstruct from even in a window with
14
17
  # no root version, exactly as a single-record activity timeline does.
15
18
  @context_required = context_required
@@ -21,8 +24,6 @@ module PaperTrailDiff
21
24
  # Returns a plan per record identity.
22
25
  #: () -> Hash[Array[String], RootVersionPlan]
23
26
  def call
24
- return {} if @records.empty?
25
-
26
27
  selected = {} #: Hash[Array[String], RootVersionPlan]
27
28
  @records.group_by(&:class).each do |model_class, records|
28
29
  select_model(model_class, records, selected)
@@ -37,33 +38,55 @@ module PaperTrailDiff
37
38
  # @rbs @version_scope: untyped
38
39
  # @rbs @live_endpoints: Hash[Array[String], untyped]?
39
40
  # @rbs @context_required: bool
41
+ # @rbs @windows: Hash[Array[String], TimeRange]
40
42
 
41
43
  #: (untyped, Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
42
44
  def select_model(model_class, records, selected)
43
- ids = records.map(&:id)
44
- in_range, chosen, trailing = model_versions(model_class, ids)
45
+ in_range, chosen, trailing = model_versions(model_class, records)
45
46
  records.each do |record|
46
- key = identity(model_class, record.id)
47
- selected[key] = versions_for(
48
- in_range.fetch(record.id.to_s, []), chosen, trailing[record.id.to_s],
49
- live_endpoint(key, record)
50
- )
47
+ key = Endpoint.identity(record)
48
+ own = own_window(key, record.id.to_s, in_range, trailing)
49
+ selected[key] = versions_for(*own, chosen, live_endpoint(key, record))
51
50
  end
52
51
  end
53
52
 
53
+ # Moved windows only start and end earlier, so the versions read for the
54
+ # widest of them hold each root's own, and the first left past a moved end.
55
+ #: (Array[String], String, Hash[String, Array[untyped]], Hash[String, untyped]) -> [Array[untyped], untyped]
56
+ def own_window(key, id, in_range, trailing)
57
+ loaded = in_range.fetch(id, [])
58
+ return [loaded, trailing[id]] if @windows.empty?
59
+
60
+ # A batch moves windows only when it has one, so this is never nil.
61
+ window = @windows.fetch(key) { @time_range } #: untyped
62
+ own, rest = loaded.partition { |version| window.include?(version.created_at) }
63
+ [own, rest.find { |version| version.created_at >= window.end_time } || trailing[id]]
64
+ end
65
+
54
66
  #: (untyped, Array[untyped]) -> [Hash[String, Array[untyped]], Set[untyped]?, Hash[String, untyped]]
55
- def model_versions(model_class, ids)
67
+ def model_versions(model_class, records)
56
68
  range = @time_range
57
69
  empty = {} #: Hash[String, untyped]
70
+ widest = widest_range(records)
58
71
  [
59
- grouped_versions(model_class, ids, range),
60
- chosen_version_ids(model_class, ids, range),
61
- range ? trailing_versions(model_class, ids, range) : empty
72
+ grouped_versions(model_class, records, widest),
73
+ chosen_version_ids(model_class, records, widest),
74
+ range ? trailing_versions(model_class, records, range) : empty
62
75
  ]
63
76
  end
64
77
 
65
- #: (Array[untyped], Set[untyped]?, untyped, untyped) -> RootVersionPlan
66
- def versions_for(in_range, chosen, after_range, live_endpoint)
78
+ #: (Array[untyped]) -> TimeRange?
79
+ def widest_range(records)
80
+ range = @time_range
81
+ return unless range
82
+
83
+ moved = records.filter_map { |record| @windows[Endpoint.identity(record)]&.begin_time }
84
+ start = [range.begin_time, *moved].min
85
+ TimeRange.new(range.exclude_end? ? (start...range.end_time) : (start..range.end_time))
86
+ end
87
+
88
+ #: (Array[untyped], untyped, Set[untyped]?, untyped) -> RootVersionPlan
89
+ def versions_for(in_range, after_range, chosen, live_endpoint)
67
90
  RootVersionSelection.new(
68
91
  in_range: in_range,
69
92
  selected: chosen ? in_range.select { |version| chosen.include?(version.id) } : in_range,
@@ -89,48 +112,31 @@ module PaperTrailDiff
89
112
  # One extra query names the selected mutations without discarding the
90
113
  # unfiltered versions the successor lookup still needs.
91
114
  #: (untyped, Array[untyped], TimeRange?) -> Set[untyped]?
92
- def chosen_version_ids(model_class, ids, range)
93
- scope = @version_scope
94
- return unless scope
95
-
96
- # A narrowed relation is the expected return. Active Support also gives
97
- # `pluck` to plain enumerables, so an array of versions works too.
98
- filtered = scope.call(range_scope(model_class, ids, range))
99
- Set.new(filtered.pluck(:id))
115
+ def chosen_version_ids(model_class, records, range)
116
+ VersionScopeFilter.new(@version_scope).chosen_ids(range_scope(model_class, records, range))
100
117
  end
101
118
 
102
119
  #: (untyped, Array[untyped], TimeRange?) -> Hash[String, Array[untyped]]
103
- def grouped_versions(model_class, ids, range)
104
- ordered(range_scope(model_class, ids, range)).group_by { |version| version.item_id.to_s }
120
+ def grouped_versions(model_class, records, range)
121
+ VersionQuery.chronological(range_scope(model_class, records, range))
122
+ .group_by { |version| version.item_id.to_s }
105
123
  end
106
124
 
107
125
  #: (untyped, Array[untyped], TimeRange?) -> untyped
108
- def range_scope(model_class, ids, range)
109
- scope = base_scope(model_class, ids)
126
+ def range_scope(model_class, records, range)
127
+ scope = base_scope(model_class, records)
110
128
  range ? range.scope(scope) : scope
111
129
  end
112
130
 
113
131
  #: (untyped, Array[untyped], TimeRange) -> Hash[String, untyped]
114
- def trailing_versions(model_class, ids, range)
115
- range.first_trailing_versions(base_scope(model_class, ids))
132
+ def trailing_versions(model_class, records, range)
133
+ range.first_trailing_versions(base_scope(model_class, records))
116
134
  end
117
135
 
118
136
  #: (untyped, Array[untyped]) -> untyped
119
- def base_scope(model_class, ids)
120
- model_class.paper_trail.version_class.where(
121
- item_type: model_class.base_class.name.to_s,
122
- item_id: ids
123
- )
124
- end
125
-
126
- #: (untyped) -> Array[untyped]
127
- def ordered(relation)
128
- VersionQuery.chronological(relation).to_a
129
- end
130
-
131
- #: (untyped, untyped) -> Array[String]
132
- def identity(model_class, id)
133
- [model_class.base_class.name.to_s, id.to_s]
137
+ def base_scope(model_class, records)
138
+ # Active Record reads each record's id.
139
+ VersionQuery.for_items(model_class, records)
134
140
  end
135
141
  end
136
142
  end
@@ -0,0 +1,133 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # One change from an activity step, flat enough for a history table or an
6
+ # export: a field that changed, or a record that appeared or disappeared,
7
+ # with the event the step attributes it to.
8
+ class ChangeRow
9
+ attr_reader :change #: Symbol
10
+ attr_reader :association_path #: Array[String]
11
+ attr_reader :association_kind #: Symbol?
12
+ # The record the row is about, or nil for the root itself.
13
+ attr_reader :record #: RecordReference?
14
+ # The field the row is about, or nil for a row about a whole record.
15
+ attr_reader :attribute #: String?
16
+ attr_reader :from #: untyped
17
+ attr_reader :to #: untyped
18
+ # The step's source boundary: for a transaction group, its first event.
19
+ attr_reader :source #: ActivityBoundary
20
+
21
+ #: (change: Symbol, association_path: Array[String], association_kind: Symbol?, record: RecordReference?, attribute: String?, from: untyped, to: untyped, source: ActivityBoundary) -> void
22
+ def initialize( # rubocop:disable Metrics/ParameterLists
23
+ change:, association_path:, association_kind:, record:, attribute:, from:, to:, source:
24
+ )
25
+ @change = change
26
+ @association_path = association_path
27
+ @association_kind = association_kind
28
+ @record = record
29
+ @attribute = attribute
30
+ @from = from
31
+ @to = to
32
+ @source = source
33
+ freeze
34
+ end
35
+
36
+ # The source's identifying fields sit beside the change rather than nested,
37
+ # so the hash is one row of a table as it stands.
38
+ #: () -> Hash[Symbol, untyped]
39
+ def to_h
40
+ {
41
+ change: change, association_path: association_path, association_kind: association_kind,
42
+ record: record&.to_h, attribute: attribute,
43
+ from: Support.serialize(from), to: Support.serialize(to)
44
+ }.merge(source_fields)
45
+ end
46
+
47
+ private
48
+
49
+ #: () -> Hash[Symbol, untyped]
50
+ def source_fields
51
+ { version_id: source.version_id, event: source.event, whodunnit: source.whodunnit,
52
+ recorded_at: source.recorded_at, transaction_id: source.transaction_id }
53
+ end
54
+ end
55
+
56
+ # Flattens one step's diff into change rows, in the diff's walking order.
57
+ #
58
+ # A row is about one record. An edited field is `:changed`. A record that
59
+ # appeared or disappeared is one `:added` or `:removed` row, followed by a
60
+ # row for each of its fields and for each record it holds, so a table can
61
+ # list a new comment's body without a second walker. That covers a record
62
+ # joining or leaving a collection, a to-one target set, cleared or replaced
63
+ # (the old target removed, then the new one added), and the root's own
64
+ # creation or deletion.
65
+ #
66
+ # Two kinds of entry add nothing a row would show. One that only groups
67
+ # others (an edited record, an association, a relationship) is left out,
68
+ # because the rows under it name the same record. A blank field of an added
69
+ # or removed record is left out too, because the record's own row already
70
+ # says it appeared or disappeared.
71
+ class ChangeRows
72
+ RECORD_ENTRIES = %i[record_added record_removed record_included].freeze
73
+ private_constant :RECORD_ENTRIES
74
+
75
+ #: (Diff, source: ActivityBoundary) -> Array[ChangeRow]
76
+ def self.call(diff, source:)
77
+ new(source).call(diff)
78
+ end
79
+
80
+ #: (ActivityBoundary) -> void
81
+ def initialize(source)
82
+ @source = source
83
+ end
84
+
85
+ #: (Diff) -> Array[ChangeRow]
86
+ def call(diff)
87
+ rows = [] #: Array[ChangeRow]
88
+ diff.each_entry do |entry|
89
+ row = row_for(entry)
90
+ rows << row if row
91
+ end
92
+ rows.freeze
93
+ end
94
+
95
+ private
96
+
97
+ # @rbs @source: ActivityBoundary
98
+
99
+ #: (TraversalEntry) -> ChangeRow?
100
+ def row_for(entry)
101
+ return changed_row(entry) if entry.kind == :attribute_changed
102
+ return presence_row(entry, nil) if RECORD_ENTRIES.include?(entry.kind)
103
+ return unless entry.kind == :attribute_included && !entry.value.nil?
104
+
105
+ presence_row(entry, entry.attribute)
106
+ end
107
+
108
+ #: (TraversalEntry) -> ChangeRow
109
+ def changed_row(entry)
110
+ value = entry.value #: ValueChange
111
+ row(entry, :changed, entry.attribute, value.from, value.to)
112
+ end
113
+
114
+ # An added record's state is the after side and a removed one's the before
115
+ # side, so a field's value goes on the side that has it.
116
+ #: (TraversalEntry, String?) -> ChangeRow
117
+ def presence_row(entry, attribute)
118
+ value = attribute ? entry.value : nil
119
+ return row(entry, :added, attribute, nil, value) if entry.state == :after
120
+
121
+ row(entry, :removed, attribute, value, nil)
122
+ end
123
+
124
+ #: (TraversalEntry, Symbol, String?, untyped, untyped) -> ChangeRow
125
+ def row(entry, change, attribute, from, to)
126
+ ChangeRow.new(
127
+ change: change, association_path: entry.association_path,
128
+ association_kind: entry.association_kind, record: entry.record,
129
+ attribute: attribute, from: from, to: to, source: @source
130
+ )
131
+ end
132
+ end
133
+ end
@@ -3,6 +3,8 @@
3
3
 
4
4
  module PaperTrailDiff
5
5
  # Compares collection snapshots with a low-allocation path for stable membership.
6
+ # Snapshots hold their records in type and ID order, so results follow it
7
+ # without sorting here.
6
8
  class CollectionComparator
7
9
  #: (AssociationSnapshot, AssociationSnapshot, record_comparer: untyped) -> void
8
10
  def initialize(from_association, to_association, record_comparer:)
@@ -50,9 +52,7 @@ module PaperTrailDiff
50
52
  pairs = aligned_changed_pairs
51
53
  return unless pairs
52
54
 
53
- pairs.sort_by { |_from, to| sortable_identity(to.identity) }.filter_map do |pair|
54
- @record_comparer.call(pair.fetch(0), pair.fetch(1))
55
- end
55
+ pairs.filter_map { |pair| @record_comparer.call(pair.fetch(0), pair.fetch(1)) }
56
56
  end
57
57
 
58
58
  #: () -> Array[[RecordSnapshot, RecordSnapshot]]?
@@ -105,13 +105,12 @@ module PaperTrailDiff
105
105
 
106
106
  #: (Hash[identity, RecordSnapshot], Hash[identity, RecordSnapshot]) -> Array[RecordSnapshot]
107
107
  def records_missing_from(records, other_records)
108
- identities = sorted_identities(records.keys - other_records.keys)
109
- identities.map { |identity| records.fetch(identity) }
108
+ (records.keys - other_records.keys).map { |identity| records.fetch(identity) }
110
109
  end
111
110
 
112
111
  #: (Hash[identity, RecordSnapshot], Hash[identity, RecordSnapshot]) -> Array[RecordChange]
113
112
  def changed_records(from_records, to_records)
114
- sorted_identities(from_records.keys & to_records.keys).filter_map do |identity|
113
+ (from_records.keys & to_records.keys).filter_map do |identity|
115
114
  from_record = from_records.fetch(identity)
116
115
  to_record = to_records.fetch(identity)
117
116
  next if from_record.equal?(to_record)
@@ -132,32 +131,6 @@ module PaperTrailDiff
132
131
  index
133
132
  end
134
133
 
135
- #: (Array[identity]) -> Array[identity]
136
- def sorted_identities(identities)
137
- identities.sort_by { |identity| sortable_identity(identity) }
138
- end
139
-
140
- # Identities sort by type first so that mixed id types stay comparable, then
141
- # naturally within one type. Ordering by the printed form instead would put
142
- # id 10 before id 2, which is deterministic but reads as unsorted wherever a
143
- # result is rendered.
144
- #: (identity) -> Array[untyped]
145
- def sortable_identity(identity)
146
- [identity.fetch(0), sortable_id(identity.fetch(1))]
147
- end
148
-
149
- # Only the order of the group numbers matters, so moving the lowest one
150
- # down or the highest one up changes nothing; the spec checks the order.
151
- # mutant:disable
152
- #: (untyped) -> Array[untyped]
153
- def sortable_id(id)
154
- case id
155
- when Numeric then [0, id]
156
- when String, Symbol then [1, id.to_s]
157
- else [2, id.inspect]
158
- end
159
- end
160
-
161
134
  #: (identity) -> void
162
135
  def raise_duplicate_identity!(identity)
163
136
  raise ArgumentError, "duplicate record identity: #{identity}"
@@ -4,12 +4,16 @@
4
4
  module PaperTrailDiff
5
5
  # Validates and executes independent comparisons with shared live endpoint loading.
6
6
  class ComparisonBatch
7
- #: (Array[comparison_input], live_loader: untyped, preparer: untyped, history_preparer: untyped, historical_snapshotter: untyped, live_normalizer: untyped) -> void
7
+ # `history_preparer` prepares roots that have a live endpoint to collect a
8
+ # graph from; `version_history_preparer` prepares roots compared only
9
+ # between versions.
10
+ #: (Array[comparison_input], live_loader: untyped, preparer: untyped, history_preparer: untyped, version_history_preparer: untyped, historical_snapshotter: untyped, live_normalizer: untyped) -> void
8
11
  def initialize( # rubocop:disable Metrics/ParameterLists
9
12
  comparisons,
10
13
  live_loader:,
11
14
  preparer:,
12
15
  history_preparer:,
16
+ version_history_preparer:,
13
17
  historical_snapshotter:,
14
18
  live_normalizer:
15
19
  )
@@ -17,6 +21,7 @@ module PaperTrailDiff
17
21
  @live_loader = live_loader
18
22
  @preparer = preparer
19
23
  @history_preparer = history_preparer
24
+ @version_history_preparer = version_history_preparer
20
25
  @historical_snapshotter = historical_snapshotter
21
26
  @live_normalizer = live_normalizer
22
27
  end
@@ -35,6 +40,7 @@ module PaperTrailDiff
35
40
  # @rbs @live_loader: untyped
36
41
  # @rbs @preparer: untyped
37
42
  # @rbs @history_preparer: untyped
43
+ # @rbs @version_history_preparer: untyped
38
44
  # @rbs @historical_snapshotter: untyped
39
45
  # @rbs @live_normalizer: untyped
40
46
 
@@ -97,20 +103,41 @@ module PaperTrailDiff
97
103
 
98
104
  #: (Array[[untyped, untyped]], Hash[identity, untyped]) -> void
99
105
  def prepare_historical_batches!(pairs, live_records)
100
- grouped = historical_versions(pairs, live_records).group_by do |version|
101
- Endpoint.model_class(version)
106
+ loaded, unloaded = historical_versions(pairs).partition do |version|
107
+ live_records.key?(Endpoint.identity(version))
102
108
  end
103
- grouped.each_value do |versions|
109
+ loaded.group_by { |version| RecordedClass.for(version) }.each_value do |versions|
104
110
  records = versions.map { |version| live_records.fetch(Endpoint.identity(version)) }.uniq
105
111
  @history_preparer.call(records, versions)
106
112
  end
113
+ prepare_version_roots!(unloaded)
114
+ end
115
+
116
+ # A root compared only between versions has no live endpoint, and its row
117
+ # may be gone. Without prepared history, PT-AT finds a has_many's children
118
+ # by the keys each version recorded after its change, so it misses a child
119
+ # that later moved to another owner. Such roots are prepared from identity
120
+ # alone, like deleted ones. Their history still reads the live rows it
121
+ # needs: a record's current row is its state after its last version.
122
+ #: (Array[untyped]) -> void
123
+ def prepare_version_roots!(versions)
124
+ versions.group_by { |version| RecordedClass.for(version) }.each do |model, group|
125
+ ids = group.map(&:item_id).uniq(&:to_s)
126
+ @version_history_preparer.call(ids.map { |id| historical_root(model, id) }, group)
127
+ end
107
128
  end
108
129
 
109
- #: (Array[[untyped, untyped]], Hash[identity, untyped]) -> Array[untyped]
110
- def historical_versions(pairs, live_records)
111
- selected = pairs.flatten.select do |endpoint|
112
- Endpoint.version?(endpoint) && live_records.key?(Endpoint.identity(endpoint))
113
- end
130
+ # The record supplies identity and model metadata only.
131
+ #: (untyped, untyped) -> untyped
132
+ def historical_root(model, id)
133
+ record = model.new
134
+ record[model.primary_key] = id
135
+ record
136
+ end
137
+
138
+ #: (Array[[untyped, untyped]]) -> Array[untyped]
139
+ def historical_versions(pairs)
140
+ selected = pairs.flatten.select { |endpoint| Endpoint.version?(endpoint) }
114
141
  selected.uniq { |version| [version.class.name, version.id] }
115
142
  end
116
143
 
@@ -167,7 +194,7 @@ module PaperTrailDiff
167
194
  requirements = {} #: Hash[untyped, bool]
168
195
  pairs.flatten.each_with_object(requirements) do |endpoint, collected|
169
196
  historical = Endpoint.version?(endpoint)
170
- model_class = historical ? Endpoint.model_class(endpoint) : endpoint.class
197
+ model_class = historical ? RecordedClass.for(endpoint) : endpoint.class
171
198
  collected[model_class] = collected.fetch(model_class, false) || historical
172
199
  end
173
200
  end
@@ -7,19 +7,40 @@ module PaperTrailDiff
7
7
  attr_reader :children #: Hash[String, AssociationTree]
8
8
 
9
9
  class << self
10
+ # Takes what `includes` takes: a name, a dotted path, a hash of names to
11
+ # what to include below them, or an array of any of these.
10
12
  #: (untyped) -> AssociationTree
11
13
  def build(values)
12
- unless valid_values?(values)
13
- raise ConfigurationError, 'associations: must be an array of strings or symbols'
14
- end
15
-
16
14
  tree = {} #: Hash[String, untyped]
17
- values.each { |value| add_path(tree, value.to_s) }
15
+ paths(values, nil).each { |path| add_path(tree, path) }
18
16
  from_hash(tree)
19
17
  end
20
18
 
21
19
  private
22
20
 
21
+ #: (untyped, String?) -> Array[String]
22
+ def paths(value, prefix)
23
+ case value
24
+ when String, Symbol then [joined(prefix, value)]
25
+ when Array then value.flat_map { |item| paths(item, prefix) }
26
+ when Hash then value.flat_map { |name, nested| nested_paths(name, nested, prefix) }
27
+ else
28
+ raise ConfigurationError,
29
+ 'associations: must be names, dotted paths, hashes of them, or arrays of these'
30
+ end
31
+ end
32
+
33
+ # `{ comments: :replies }` names comments as well as their replies.
34
+ #: (untyped, untyped, String?) -> Array[String]
35
+ def nested_paths(name, nested, prefix)
36
+ paths(name, prefix).flat_map { |path| [path, *paths(nested, path)] }
37
+ end
38
+
39
+ #: (String?, String | Symbol) -> String
40
+ def joined(prefix, name)
41
+ prefix ? "#{prefix}.#{name}" : name.to_s
42
+ end
43
+
23
44
  #: (Hash[String, untyped], String) -> void
24
45
  def add_path(tree, path)
25
46
  segments = path.split('.', -1)
@@ -39,13 +60,6 @@ module PaperTrailDiff
39
60
  end
40
61
  new(children)
41
62
  end
42
-
43
- #: (untyped) -> bool
44
- def valid_values?(values)
45
- values.is_a?(Array) && values.all? do |value|
46
- value.is_a?(String) || value.is_a?(Symbol)
47
- end
48
- end
49
63
  end
50
64
 
51
65
  #: (Hash[String, AssociationTree]) -> void
@@ -166,5 +180,14 @@ module PaperTrailDiff
166
180
  external_path = path.empty? ? ROOT_PATH : path
167
181
  (all + paths.fetch(external_path, [])).uniq.freeze
168
182
  end
183
+
184
+ # The names to leave out of what a version recorded. A root version is
185
+ # known to be the root's, so its own path's names apply; any other version
186
+ # does not say which path reached it, so only the names ignored everywhere
187
+ # do.
188
+ #: (root: bool) -> Array[String]
189
+ def recorded_attributes(root:)
190
+ root ? attributes_for('') : all
191
+ end
169
192
  end
170
193
  end