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
@@ -4,29 +4,31 @@
4
4
  module PaperTrailDiff
5
5
  # Expands the explicit association tree into a request-scoped PreparedHistory.
6
6
  class PreparedHistoryLoader
7
- #: (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?root_ids: Array[untyped], ?start_at: untyped, ?end_at: untyped, ?live_records: Array[untyped]) -> void
7
+ # Without `end_at`, the activity range closes on the last root version.
8
+ #: (untyped, root_ids: Array[untyped], root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, start_at: untyped, end_at: untyped, live_records: Array[untyped]) -> void
8
9
  def initialize( # rubocop:disable Metrics/ParameterLists
9
10
  record,
11
+ root_ids:,
10
12
  root_versions:,
11
13
  tree:,
12
14
  traversal:,
13
- root_ids: [record.id],
14
- start_at: root_versions.first.created_at,
15
- end_at: nil,
16
- live_records: []
15
+ start_at:,
16
+ end_at:,
17
+ live_records:
17
18
  )
18
19
  @record = record
19
20
  @root_ids = root_ids
20
21
  @root_versions = root_versions
21
22
  @tree = tree
22
23
  @traversal = traversal
24
+ start_at = VersionBoundary.transaction_start(root_versions, start_at)
23
25
  @records = PreparedRecordIndex.new(start_at, end_at: end_at, live_records: live_records)
24
- activity = PreparedActivityIndex.new(
26
+ @activity = PreparedActivityIndex.new(
25
27
  @records, root_versions, start_at: start_at, end_at: end_at || root_versions.last.created_at
26
28
  )
27
- @history = PreparedHistory.new(@records, activity_index: activity)
29
+ @history = PreparedHistory.new(@records, activity_index: @activity)
28
30
  @edges = PreparedEdgeLoader.new(@records, root_versions, start_at: start_at)
29
- @prepared = {} #: Hash[Array[String], Array[String]]
31
+ @prepared = {} #: Hash[untyped, Array[String]]
30
32
  end
31
33
 
32
34
  #: () -> PreparedHistory
@@ -44,20 +46,18 @@ module PaperTrailDiff
44
46
  # @rbs @tree: AssociationTree
45
47
  # @rbs @traversal: AssociationTraversal
46
48
  # @rbs @records: PreparedRecordIndex
49
+ # @rbs @activity: PreparedActivityIndex
47
50
  # @rbs @history: PreparedHistory
48
51
  # @rbs @edges: PreparedEdgeLoader
49
- # @rbs @prepared: Hash[Array[String], Array[String]]
52
+ # @rbs @prepared: Hash[untyped, Array[String]]
50
53
 
51
54
  #: (untyped, Array[untyped], AssociationTree, path: String) -> void
52
55
  def load_node(model_class, ids, tree, path:)
53
- @history.activity_index&.register(model_class, ids)
56
+ @activity.register(model_class, ids)
54
57
  @traversal.reflections_for(model_class, tree, path: path).each do |reflection|
55
- subtree = tree.child(reflection.name)
56
- next unless subtree
57
-
58
+ subtree = tree.child(reflection.name) #: AssociationTree
58
59
  groups = prepare_reflection(model_class, ids, reflection)
59
- load_groups(groups)
60
- child_path = Support.association_path(path, reflection.name.to_s)
60
+ child_path = Support.association_path(path, reflection.name)
61
61
  groups.each_value do |group|
62
62
  load_node(group.fetch(:model), group.fetch(:ids), subtree, path: child_path)
63
63
  end
@@ -66,70 +66,66 @@ module PaperTrailDiff
66
66
 
67
67
  #: (untyped, Array[untyped], untyped) -> Hash[String, Hash[Symbol, untyped]]
68
68
  def prepare_reflection(owner_class, owner_ids, reflection)
69
- return prepare_through(owner_class, owner_ids, reflection) if reflection.options[:through]
69
+ return prepare_through(owner_class, owner_ids, reflection) if reflection.through_reflection?
70
70
 
71
71
  prepare_edge(owner_class, owner_ids, reflection)
72
72
  end
73
73
 
74
+ # Either part can itself be a through, which has no key of its own to
75
+ # read, so each part is prepared as what it is. Like an edge, it returns
76
+ # every group it holds, not only those of these owners.
74
77
  #: (untyped, Array[untyped], untyped) -> Hash[String, Hash[Symbol, untyped]]
75
78
  def prepare_through(owner_class, owner_ids, reflection)
76
- through_groups = prepare_edge(owner_class, owner_ids, reflection.through_reflection)
79
+ through_groups = prepare_reflection(owner_class, owner_ids, reflection.through_reflection)
77
80
  targets = {} #: Hash[String, Hash[Symbol, untyped]]
78
81
  through_groups.each_value do |group|
79
- load_groups({ group.fetch(:model).name.to_s => group })
80
- source = prepare_edge(group.fetch(:model), group.fetch(:ids), reflection.source_reflection)
82
+ source = prepare_reflection(group.fetch(:model), group.fetch(:ids),
83
+ reflection.source_reflection)
81
84
  targets = merge_groups(targets, source)
82
85
  end
83
86
  @history.merge_edge(owner_class, reflection, targets)
84
- @history.mark_unsupported(owner_class, reflection) if deferred_macro?(reflection)
85
- targets
86
87
  end
87
88
 
88
89
  #: (untyped, Array[untyped], untyped) -> Hash[String, Hash[Symbol, untyped]]
89
90
  def prepare_edge(owner_class, owner_ids, reflection)
90
- missing = unprepared_ids(owner_class, owner_ids, reflection)
91
+ missing = unprepared_ids(owner_ids, reflection)
91
92
  return @history.edge(owner_class, reflection) if missing.empty?
92
93
 
93
- load_records(owner_class, missing) if reflection.macro == :belongs_to
94
94
  groups, memberships = @edges.call(owner_class, missing, reflection)
95
95
  @history.merge_edge(owner_class, reflection, groups)
96
96
  @history.register_habtm(owner_class, reflection, memberships) if memberships
97
- mark_prepared(owner_class, missing, reflection)
97
+ mark_prepared(missing, reflection)
98
98
  mark_unsupported(owner_class, reflection, groups)
99
99
  load_groups(groups)
100
100
  @history.edge(owner_class, reflection)
101
101
  end
102
102
 
103
- #: (untyped, Array[untyped], untyped) -> Array[untyped]
104
- def unprepared_ids(owner_class, ids, reflection)
105
- prepared = @prepared.fetch(edge_key(owner_class, reflection), [])
103
+ # A reflection belongs to the class that declares it, so it alone names
104
+ # the edge; a subclass that inherits it reads the same records.
105
+ #: (Array[untyped], untyped) -> Array[untyped]
106
+ def unprepared_ids(ids, reflection)
107
+ prepared = @prepared.fetch(reflection, [])
106
108
  ids.reject { |id| prepared.include?(id.to_s) }
107
109
  end
108
110
 
109
- #: (untyped, Array[untyped], untyped) -> void
110
- def mark_prepared(owner_class, ids, reflection)
111
- key = edge_key(owner_class, reflection)
112
- @prepared[key] = (@prepared.fetch(key, []) | ids.map(&:to_s))
111
+ #: (Array[untyped], untyped) -> void
112
+ def mark_prepared(ids, reflection)
113
+ @prepared[reflection] = (@prepared.fetch(reflection, []) | ids.map(&:to_s))
113
114
  end
114
115
 
115
116
  #: (untyped, untyped, Hash[String, Hash[Symbol, untyped]]) -> void
116
117
  def mark_unsupported(owner_class, reflection, groups)
117
- unsupported = deferred_macro?(reflection) || reflection.foreign_key.is_a?(Array) ||
118
+ unsupported = reflection.foreign_key.is_a?(Array) ||
118
119
  groups.values.any? { |group| !versioned?(group.fetch(:model)) }
119
120
  @history.mark_unsupported(owner_class, reflection) if unsupported
120
121
  end
121
122
 
122
- #: (untyped) -> bool
123
- def deferred_macro?(reflection)
124
- reflection.options[:through] && !reflection.source_reflection.belongs_to?
125
- end
126
-
127
123
  #: (Hash[String, Hash[Symbol, untyped]]) -> void
128
124
  def load_groups(groups)
129
125
  groups.each_value do |group|
130
126
  model = group.fetch(:model)
131
127
  ids = group.fetch(:ids)
132
- @history.activity_index&.register(model, ids)
128
+ @activity.register(model, ids)
133
129
  load_records(model, ids)
134
130
  end
135
131
  end
@@ -144,11 +140,6 @@ module PaperTrailDiff
144
140
  Support.versioned?(model_class)
145
141
  end
146
142
 
147
- #: (untyped, untyped) -> Array[String]
148
- def edge_key(owner_class, reflection)
149
- [owner_class.base_class.name.to_s, reflection.name.to_s]
150
- end
151
-
152
143
  #: (Hash[String, Hash[Symbol, untyped]], Hash[String, Hash[Symbol, untyped]]) -> Hash[String, Hash[Symbol, untyped]]
153
144
  def merge_groups(left, right)
154
145
  Support.merge_record_groups(left, right)
@@ -133,6 +133,17 @@ module PaperTrailDiff
133
133
  state_before(boundary)&.instantiate
134
134
  end
135
135
 
136
+ # A record created in the boundary's own transaction has no state before
137
+ # it, yet a HABTM checkpoint saved later in that transaction records it as
138
+ # a member. Such a member is read as it was created.
139
+ #: (untyped) -> untyped
140
+ def record_created_in(boundary)
141
+ index = transaction_index(boundary)
142
+ return unless index && versions.fetch(index).event == 'create'
143
+
144
+ state_after(index)&.instantiate
145
+ end
146
+
136
147
  #: (untyped) -> PreparedRecordState?
137
148
  def state_before(boundary)
138
149
  index = boundary_index(boundary)
@@ -163,7 +174,23 @@ module PaperTrailDiff
163
174
  live ? [*recorded, live] : recorded
164
175
  end
165
176
 
166
- #: (untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
177
+ # The classes the record had at any point, or either side of one version.
178
+ #: (?untyped) -> Array[untyped]
179
+ def model_classes(version = nil)
180
+ return states.map(&:model_class) unless version
181
+
182
+ states_around(version).map(&:model_class)
183
+ end
184
+
185
+ # The states either side of one version; a create has none before it and a
186
+ # destroy none after.
187
+ #: (untyped) -> Array[PreparedRecordState]
188
+ def states_around(version)
189
+ index = @version_positions.fetch(version.id.to_s)
190
+ [state_for(version), state_after(index)].compact
191
+ end
192
+
193
+ #: (untyped) -> [PreparedRecordState, PreparedRecordState]?
167
194
  def transition(version)
168
195
  index = @version_positions[version.id.to_s]
169
196
  return unless index
@@ -172,7 +199,7 @@ module PaperTrailDiff
172
199
  after = state_after(index)
173
200
  return unless before && after && before.model_class == after.model_class
174
201
 
175
- [before.attributes, after.attributes]
202
+ [before, after]
176
203
  end
177
204
 
178
205
  private
@@ -212,7 +239,7 @@ module PaperTrailDiff
212
239
 
213
240
  #: (untyped) -> Integer?
214
241
  def transaction_index(boundary)
215
- transaction_id = boundary.transaction_id if boundary.respond_to?(:transaction_id)
242
+ transaction_id = VersionBoundary.transaction_id(boundary)
216
243
  return unless transaction_id
217
244
 
218
245
  @transaction_positions[transaction_id]
@@ -222,9 +249,7 @@ module PaperTrailDiff
222
249
  def build_transaction_positions
223
250
  positions = {} #: Hash[untyped, Integer]
224
251
  @versions.each_with_index do |version, index|
225
- next unless version.respond_to?(:transaction_id)
226
-
227
- transaction_id = version.transaction_id
252
+ transaction_id = VersionBoundary.transaction_id(version)
228
253
  positions[transaction_id] ||= index if transaction_id
229
254
  end
230
255
  positions.freeze
@@ -288,6 +313,11 @@ module PaperTrailDiff
288
313
  @series.fetch(identity(model_class, id)).record_before(boundary)
289
314
  end
290
315
 
316
+ #: (untyped, untyped, untyped) -> untyped
317
+ def record_created_in(model_class, id, boundary)
318
+ @series.fetch(identity(model_class, id)).record_created_in(boundary)
319
+ end
320
+
291
321
  #: (untyped, untyped, untyped) -> [bool, PreparedRecordState?]
292
322
  def snapshot_state_before(model_class, id, boundary)
293
323
  series = @series[identity(model_class, id)]
@@ -301,9 +331,15 @@ module PaperTrailDiff
301
331
  [!prepared.nil?, prepared]
302
332
  end
303
333
 
334
+ # Typed as a reified record's attributes are. A JSON or JSONB `object`
335
+ # column stores times and dates as strings, which PaperTrail does not cast
336
+ # back, and the transition is carried into snapshots built from records.
304
337
  #: (untyped, untyped, untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
305
338
  def transition(model_class, id, version)
306
- @series[identity(model_class, id)]&.transition(version)
339
+ states = @series[identity(model_class, id)]&.transition(version)
340
+ return unless states
341
+
342
+ [typed_attributes(states.fetch(0)), typed_attributes(states.fetch(1))]
307
343
  end
308
344
 
309
345
  #: (untyped, untyped, untyped, ?direct: bool) -> [bool, untyped]
@@ -337,6 +373,16 @@ module PaperTrailDiff
337
373
  @series.fetch(identity(model_class, id)).versions
338
374
  end
339
375
 
376
+ #: (untyped, untyped, ?untyped) -> Array[untyped]
377
+ def model_classes(model_class, id, version = nil)
378
+ @series.fetch(identity(model_class, id)).model_classes(version)
379
+ end
380
+
381
+ #: (untyped, untyped, untyped) -> Array[PreparedRecordState]
382
+ def states_around(model_class, id, version)
383
+ @series.fetch(identity(model_class, id)).states_around(version)
384
+ end
385
+
340
386
  #: (untyped, untyped) -> bool
341
387
  def loaded?(model_class, id)
342
388
  @series.key?(identity(model_class, id))
@@ -344,6 +390,17 @@ module PaperTrailDiff
344
390
 
345
391
  private
346
392
 
393
+ # A model whose records need their own initialization is cast by
394
+ # instantiating it, as reify does.
395
+ #: (PreparedRecordState) -> Hash[untyped, untyped]
396
+ def typed_attributes(state)
397
+ @direct_states[state] = @direct_loader.complete(state) unless @direct_states.key?(state)
398
+ typed = @direct_states[state]
399
+ return typed.attributes if typed
400
+
401
+ PreparedRecordState.new(state.instantiate).attributes
402
+ end
403
+
347
404
  #: (untyped, String) -> bool
348
405
  def generated_reader?(model, name)
349
406
  model.define_attribute_methods
@@ -49,7 +49,7 @@ module PaperTrailDiff
49
49
  subtree = tree.child(reflection.name)
50
50
  return [false, nil] unless subtree
51
51
 
52
- child_path = Support.association_path(path, reflection.name.to_s)
52
+ child_path = Support.association_path(path, reflection.name)
53
53
  records = [] #: Array[RecordSnapshot]
54
54
  states.each do |state|
55
55
  supported, snapshot = build(state, boundary, subtree, normalizer, history,
@@ -2,71 +2,161 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- # Reads plain direct edges without creating AR records for their members.
5
+ # Reads plain edges without creating AR records for their members: direct
6
+ # edges, polymorphic `belongs_to`, and `has_many :through` built from them.
6
7
  class PreparedStateAssociationReader
7
- #: (PreparedRecordIndex, untyped) -> void
8
- def initialize(records, edges)
8
+ #: (PreparedRecordIndex, untyped, ScopeCondition::Cache) -> void
9
+ def initialize(records, edges, conditions)
9
10
  @records = records
10
11
  @edges = edges
12
+ @conditions = conditions
11
13
  end
12
14
 
13
- #: (PreparedRecordState, untyped, untyped) -> [bool, Array[PreparedRecordState]]
14
- def call(owner, reflection, boundary)
15
- return [false, []] unless supported?(reflection)
15
+ # Unranked, as a part of a has_many through is read, it returns every row
16
+ # the part's conditions admit, a record reached twice appearing twice.
17
+ #: (PreparedRecordState, untyped, untyped, ?ranked: bool) -> [bool, Array[PreparedRecordState]]
18
+ def call(owner, reflection, boundary, ranked: true)
19
+ return [false, []] unless supported?(reflection, ranked)
20
+ return through(owner, reflection, boundary, ranked) if reflection.options[:through]
21
+ return target(owner, reflection, boundary, ranked) if reflection.belongs_to?
16
22
 
17
- if reflection.belongs_to?
18
- id = owner.attributes[reflection.foreign_key.to_s]
19
- return [true, []] if id.nil?
20
-
21
- handled, state = @records.snapshot_state_before(reflection.klass, id, boundary)
22
- return [handled, state ? [state] : []]
23
- end
24
- children(owner, reflection, boundary)
23
+ children(owner, reflection, boundary, ranked)
25
24
  end
26
25
 
27
26
  private
28
27
 
29
28
  # @rbs @records: PreparedRecordIndex
30
29
  # @rbs @edges: untyped
30
+ # @rbs @conditions: ScopeCondition::Cache
31
+
32
+ # A polymorphic target's class is known only once a record names it, so
33
+ # `target` reads its scope for each record instead.
34
+ #: (untyped, bool) -> bool
35
+ def supported?(reflection, ranked)
36
+ !reflection.foreign_key.is_a?(Array) &&
37
+ %i[belongs_to has_one has_many].include?(reflection.macro) &&
38
+ (reflection.polymorphic? || !@conditions.call(reflection, ranked: ranked).nil?)
39
+ end
40
+
41
+ #: (PreparedRecordState, untyped, bool, ?untyped) -> bool
42
+ def in_scope?(state, reflection, ranked, model_class = reflection.klass)
43
+ condition = @conditions.call(reflection, model_class, ranked: ranked) #: ScopeCondition
44
+ condition.matches?(state.attributes)
45
+ end
46
+
47
+ # A type that names no class, or a class whose scope cannot be read as
48
+ # conditions, is left to the record path, which raises for the first and
49
+ # reads the second through its association.
50
+ #: (PreparedRecordState, untyped, untyped, bool) -> [bool, Array[PreparedRecordState]]
51
+ def target(owner, reflection, boundary, ranked)
52
+ id = owner.attributes[reflection.foreign_key.to_s]
53
+ return [true, []] if id.nil?
54
+
55
+ model_class = target_class(owner, reflection)
56
+ return [false, []] unless model_class &&
57
+ @conditions.call(reflection, model_class, ranked: ranked)
31
58
 
32
- #: (untyped) -> bool
33
- def supported?(reflection)
34
- !reflection.options[:through] && !reflection.polymorphic? && reflection.scope.nil? &&
35
- !reflection.klass.default_scopes? && !reflection.foreign_key.is_a?(Array) &&
36
- %i[belongs_to has_one has_many].include?(reflection.macro)
59
+ handled, state = @records.snapshot_state_before(model_class, id, boundary)
60
+ [handled, state && in_scope?(state, reflection, ranked, model_class) ? [state] : []]
37
61
  end
38
62
 
39
- #: (PreparedRecordState, untyped, untyped) -> [bool, Array[PreparedRecordState]]
40
- def children(owner, reflection, boundary)
63
+ #: (PreparedRecordState, untyped) -> untyped
64
+ def target_class(owner, reflection)
65
+ return reflection.klass unless reflection.polymorphic?
66
+
67
+ AssociationTraversal.named_class(owner.attributes[reflection.foreign_type].to_s)
68
+ end
69
+
70
+ # The members of each join record the owner had at the boundary, as
71
+ # PreparedHistory#through_records reads them from records. Under
72
+ # `source_type:`, only join records of that type count. A has_many
73
+ # through reads its parts unranked, as its query does.
74
+ #: (PreparedRecordState, untyped, untyped, bool) -> [bool, Array[PreparedRecordState]]
75
+ def through(owner, reflection, boundary, ranked)
76
+ parts_ranked = ranked && !reflection.collection?
77
+ handled, joins = call(owner, reflection.through_reflection, boundary, ranked: parts_ranked)
78
+ return [false, []] unless handled
79
+
80
+ rows = [] #: Array[PreparedRecordState]
81
+ joins.each do |join|
82
+ next unless typed_join?(reflection, join)
83
+
84
+ handled, states = call(join, reflection.source_reflection, boundary, ranked: parts_ranked)
85
+ return [false, []] unless handled
86
+
87
+ rows.concat(states)
88
+ end
89
+ [true, through_members(reflection, rows, ranked)]
90
+ end
91
+
92
+ # The through's own scope applies after its parts' scopes, to each row,
93
+ # and a ranked read then keeps a record reached twice as one member.
94
+ #: (untyped, Array[PreparedRecordState], bool) -> Array[PreparedRecordState]
95
+ def through_members(reflection, rows, ranked)
96
+ condition = @conditions.call(reflection, ranked: ranked) #: ScopeCondition
97
+ members = condition.members(rows)
98
+ return members unless ranked
99
+
100
+ first_if_one(reflection, members.uniq { |state| identity(state) })
101
+ end
102
+
103
+ # A has_one keeps the first of its records.
104
+ #: (untyped, Array[PreparedRecordState]) -> Array[PreparedRecordState]
105
+ def first_if_one(reflection, states)
106
+ reflection.collection? ? states : states.first(1)
107
+ end
108
+
109
+ #: (untyped, PreparedRecordState) -> bool
110
+ def typed_join?(reflection, join)
111
+ AssociationTraversal.source_type_member?(reflection, join.attributes[reflection.foreign_type])
112
+ end
113
+
114
+ # A record reached through two join records is one member.
115
+ #: (PreparedRecordState) -> Array[untyped]
116
+ def identity(state)
117
+ model = state.model_class
118
+ [model.base_class.name, *Array(model.primary_key).map { |key| state.attributes[key].to_s }]
119
+ end
120
+
121
+ #: (PreparedRecordState, untyped, untyped, bool) -> [bool, Array[PreparedRecordState]]
122
+ def children(owner, reflection, boundary, ranked)
41
123
  selected = [] #: Array[PreparedRecordState]
42
124
  @edges.call(owner.model_class, reflection).each_value do |group|
43
125
  ids_for(group, owner).each do |id|
44
126
  handled, child = @records.snapshot_state_before(group.fetch(:model), id, boundary)
45
127
  return [false, []] unless handled
46
128
 
47
- selected << child if child && member?(child, owner, reflection)
129
+ selected << child if child && member?(child, owner, reflection, ranked)
48
130
  end
49
131
  end
50
- [true, reflection.collection? ? selected : selected.first(1)]
132
+ return [true, selected] unless ranked
133
+
134
+ condition = @conditions.call(reflection) #: ScopeCondition
135
+ [true, first_if_one(reflection, condition.rank(selected))]
51
136
  end
52
137
 
53
138
  #: (untyped, PreparedRecordState) -> Array[untyped]
54
139
  def ids_for(group, owner)
55
140
  owners = group[:owners]
56
- id = owner.attributes[owner.model_class.primary_key].to_s
57
141
  empty = [] #: Array[untyped]
58
- owners ? owners.fetch(id, empty) : group.fetch(:ids)
142
+ owners ? owners.fetch(owner_id(owner), empty) : group.fetch(:ids)
59
143
  end
60
144
 
61
- #: (PreparedRecordState, PreparedRecordState, untyped) -> bool
62
- def member?(child, owner, reflection)
63
- owner_id = owner.attributes[owner.model_class.primary_key].to_s
64
- return false unless child.attributes[reflection.foreign_key.to_s].to_s == owner_id
145
+ #: (PreparedRecordState, PreparedRecordState, untyped, bool) -> bool
146
+ def member?(child, owner, reflection, ranked)
147
+ return false unless child.attributes[reflection.foreign_key.to_s].to_s == owner_id(owner)
148
+ return false unless AssociationTraversal.sti_member?(reflection.klass, child.attributes)
149
+ return false unless in_scope?(child, reflection, ranked)
65
150
  return true unless reflection.options[:as]
66
151
 
67
152
  matching_type?(child, owner.model_class, reflection)
68
153
  end
69
154
 
155
+ #: (PreparedRecordState) -> String
156
+ def owner_id(owner)
157
+ owner.attributes[owner.model_class.primary_key].to_s
158
+ end
159
+
70
160
  #: (PreparedRecordState, untyped, untyped) -> bool
71
161
  def matching_type?(child, model, reflection)
72
162
  types = [model.name, model.base_class.name,
@@ -0,0 +1,83 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # The changes PaperTrail wrote with one version, typed by the version's model.
6
+ #
7
+ # A step's diff compares reconstructed states, so it also holds whatever was
8
+ # saved without a version before the next one was read. This is the other
9
+ # account of the same event: only what PaperTrail recorded for it. Comparing
10
+ # the two is how a caller tells an unrecorded write from the event's own edit.
11
+ #
12
+ # PaperTrail's `version.changeset` finds the model through `version.item`,
13
+ # which is a query per version and nothing at all once the record is deleted.
14
+ # The version already names its model, so neither is needed here.
15
+ class RecordedChanges
16
+ IGNORE_NAMES_REQUIRED = 'ignore: must be an array of strings or symbols; a version ' \
17
+ 'has no association path for paths: to match'
18
+ private_constant :IGNORE_NAMES_REQUIRED
19
+
20
+ #: (untyped, ignore: untyped) -> Hash[String, ValueChange]?
21
+ def self.call(version, ignore:)
22
+ new(version, ignore: ignore).call
23
+ end
24
+
25
+ #: (untyped, ignore: untyped) -> void
26
+ def initialize(version, ignore:)
27
+ @version = version
28
+ @ignore = ignore
29
+ end
30
+
31
+ #: () -> Hash[String, ValueChange]?
32
+ def call
33
+ raise InvalidEndpointError, 'expected a PaperTrail version' unless Endpoint.version?(@version)
34
+
35
+ ignored = ignored_names
36
+ return unless recorded?
37
+
38
+ model_class = Endpoint.model_class(@version)
39
+ changes = ActivityEventRecordResolver.new.deserialized_changeset(@version, model_class)
40
+ return if changes.nil?
41
+
42
+ value_changes(changes, Array(model_class.primary_key) + ignored)
43
+ end
44
+
45
+ private
46
+
47
+ # @rbs @version: untyped
48
+ # @rbs @ignore: untyped
49
+
50
+ # Validated before anything is read, so a bad option fails the same way
51
+ # whether or not this version happened to record changes. Subclasses of
52
+ # Array and String pass, as in other methods' `ignore:`; Symbol has none.
53
+ #: () -> Array[String]
54
+ def ignored_names
55
+ valid = @ignore.is_a?(Array) && @ignore.all? do |name|
56
+ name.is_a?(String) || name.instance_of?(Symbol)
57
+ end
58
+ raise ConfigurationError, IGNORE_NAMES_REQUIRED unless valid
59
+
60
+ @ignore.map(&:to_s)
61
+ end
62
+
63
+ # Without the column, or with it left empty for this version, nothing was
64
+ # recorded. That is not the same answer as a recorded empty changeset.
65
+ #: () -> bool
66
+ def recorded?
67
+ @version.class.column_names.include?('object_changes') && !@version.object_changes.nil?
68
+ end
69
+
70
+ # Primary keys identify the record rather than describe it, as in a diff.
71
+ #: (untyped, Array[String]) -> Hash[String, ValueChange]
72
+ def value_changes(changes, excluded)
73
+ recorded = {} #: Hash[String, ValueChange]
74
+ changes.each do |name, values|
75
+ key = name.to_s
76
+ next if excluded.include?(key)
77
+
78
+ recorded[key] = ValueChange.new(from: values.first, to: values.last)
79
+ end
80
+ recorded.sort.to_h.freeze
81
+ end
82
+ end
83
+ end
@@ -0,0 +1,53 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # The class a record had at one version, which decides the associations it
6
+ # can have. Without an `item_subtype` column PaperTrail stores only the base
7
+ # class, so an STI subclass is read from the stored inheritance column: the
8
+ # state before the change, or for a create, the value it was created with.
9
+ # A version that stored neither stays on the base class.
10
+ module RecordedClass
11
+ module_function
12
+
13
+ #: (untyped) -> untyped
14
+ def for(version)
15
+ model = Endpoint.model_class(version)
16
+ return model unless sti_base?(model)
17
+
18
+ type = stored_type(version, model).to_s
19
+ type.empty? ? model : model.sti_class_for(type)
20
+ rescue StandardError => e
21
+ raise unless subclass_not_found?(e)
22
+
23
+ raise InvalidEndpointError, "cannot resolve endpoint model: #{type}", cause: e
24
+ end
25
+
26
+ #: (untyped) -> bool
27
+ def sti_base?(model)
28
+ model.base_class == model && model.columns_hash.key?(model.inheritance_column.to_s)
29
+ end
30
+ private_class_method :sti_base?
31
+
32
+ #: (untyped, untyped) -> untyped
33
+ def stored_type(version, model)
34
+ column = model.inheritance_column.to_s
35
+ if version.object
36
+ attributes = version.object_deserialized
37
+ return attributes.is_a?(Hash) ? attributes[column] || attributes[column.to_sym] : nil
38
+ end
39
+
40
+ changes = ActivityEventRecordResolver.new.deserialized_changeset(version, model)
41
+ values = changes[column] if changes.respond_to?(:key?) && changes.key?(column)
42
+ values.last if values.is_a?(Array)
43
+ end
44
+ private_class_method :stored_type
45
+
46
+ #: (StandardError) -> bool
47
+ def subclass_not_found?(error)
48
+ active_record = Object.const_get(:ActiveRecord) #: untyped
49
+ error.is_a?(active_record.const_get(:SubclassNotFound))
50
+ end
51
+ private_class_method :subclass_not_found?
52
+ end
53
+ end
@@ -14,9 +14,11 @@ module PaperTrailDiff
14
14
  # An error is a specification, so it names the way out as well as the wall.
15
15
  # A window ending at the present can never gain a later version, which makes
16
16
  # "write a checkpoint afterwards" impossible advice on its own.
17
+ # A window closes on the current record when it reaches the present, so
18
+ # this is raised only when there is none to read.
17
19
  INCOMPLETE = 'time range requires a later root version to reconstruct its ' \
18
- 'final change: pass close_on: :current to end at current state, ' \
19
- 'or narrow the window to end before the last recorded version'
20
+ 'final change, and there is no current record to end at: narrow ' \
21
+ 'the window to end before the last recorded version'
20
22
 
21
23
  #: (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?filtered: bool, ?live_endpoint: untyped) -> void
22
24
  def initialize( # rubocop:disable Metrics/ParameterLists