paper_trail_diff 0.16.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 +566 -1
  3. data/README.md +42 -7
  4. data/docs/architecture.md +7 -5
  5. data/docs/performance.md +86 -38
  6. data/docs/reference.md +309 -92
  7. data/docs/testing.md +240 -32
  8. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +2 -16
  9. data/lib/paper_trail_diff/activity_boundary.rb +55 -34
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +46 -57
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +3 -13
  12. data/lib/paper_trail_diff/activity_collection_route_updater.rb +1 -1
  13. data/lib/paper_trail_diff/activity_event.rb +33 -21
  14. data/lib/paper_trail_diff/activity_event_record_resolver.rb +16 -116
  15. data/lib/paper_trail_diff/activity_event_route_finder.rb +29 -29
  16. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +2 -7
  17. data/lib/paper_trail_diff/activity_history.rb +90 -49
  18. data/lib/paper_trail_diff/activity_range.rb +9 -35
  19. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +74 -40
  20. data/lib/paper_trail_diff/activity_root_steps.rb +10 -13
  21. data/lib/paper_trail_diff/activity_scope_filter.rb +77 -0
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +12 -15
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +37 -15
  24. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +35 -43
  25. data/lib/paper_trail_diff/activity_timeline_builder.rb +194 -249
  26. data/lib/paper_trail_diff/activity_transaction_grouper.rb +3 -1
  27. data/lib/paper_trail_diff/activity_tree_filter.rb +54 -13
  28. data/lib/paper_trail_diff/activity_version_collector.rb +72 -138
  29. data/lib/paper_trail_diff/activity_view.rb +22 -11
  30. data/lib/paper_trail_diff/analysis.rb +19 -5
  31. data/lib/paper_trail_diff/analysis_batch.rb +16 -58
  32. data/lib/paper_trail_diff/approximate_paths.rb +4 -8
  33. data/lib/paper_trail_diff/association_activity_edge.rb +5 -24
  34. data/lib/paper_trail_diff/association_activity_selection.rb +10 -18
  35. data/lib/paper_trail_diff/association_discovery.rb +1 -6
  36. data/lib/paper_trail_diff/association_key.rb +9 -6
  37. data/lib/paper_trail_diff/association_traversal.rb +49 -6
  38. data/lib/paper_trail_diff/batch_boundary_resolver.rb +33 -42
  39. data/lib/paper_trail_diff/batch_preload.rb +2 -12
  40. data/lib/paper_trail_diff/batched_root_analyses.rb +72 -0
  41. data/lib/paper_trail_diff/batched_root_analyzer.rb +16 -14
  42. data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
  43. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +27 -31
  44. data/lib/paper_trail_diff/change_attribution.rb +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 -37
  49. data/lib/paper_trail_diff/deleted_root_filter.rb +3 -6
  50. data/lib/paper_trail_diff/deprecation.rb +4 -43
  51. data/lib/paper_trail_diff/diagnostics.rb +1 -2
  52. data/lib/paper_trail_diff/direct_record_state_loader.rb +8 -1
  53. data/lib/paper_trail_diff/endpoint.rb +78 -44
  54. data/lib/paper_trail_diff/errors.rb +2 -9
  55. data/lib/paper_trail_diff/fallback_paths.rb +2 -5
  56. data/lib/paper_trail_diff/habtm_transaction_owners.rb +5 -3
  57. data/lib/paper_trail_diff/historical_association_reifier.rb +3 -1
  58. data/lib/paper_trail_diff/historical_filter.rb +40 -15
  59. data/lib/paper_trail_diff/historical_snapshot_store.rb +80 -38
  60. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  61. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +11 -7
  62. data/lib/paper_trail_diff/live_endpoint_provider.rb +7 -23
  63. data/lib/paper_trail_diff/live_graph_collector.rb +3 -3
  64. data/lib/paper_trail_diff/nested_comparator.rb +46 -19
  65. data/lib/paper_trail_diff/net_change.rb +276 -0
  66. data/lib/paper_trail_diff/own_window.rb +35 -0
  67. data/lib/paper_trail_diff/paper_trail_adapter.rb +40 -45
  68. data/lib/paper_trail_diff/prepared_activity_index.rb +170 -42
  69. data/lib/paper_trail_diff/prepared_child_candidates.rb +58 -0
  70. data/lib/paper_trail_diff/prepared_edge_loader.rb +43 -107
  71. data/lib/paper_trail_diff/prepared_history.rb +20 -31
  72. data/lib/paper_trail_diff/prepared_history_loader.rb +46 -9
  73. data/lib/paper_trail_diff/prepared_record_index.rb +137 -47
  74. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +16 -0
  75. data/lib/paper_trail_diff/prepared_state_association_reader.rb +17 -19
  76. data/lib/paper_trail_diff/read_snapshot.rb +41 -19
  77. data/lib/paper_trail_diff/recorded_changes.rb +10 -11
  78. data/lib/paper_trail_diff/recorded_changes_reader.rb +60 -0
  79. data/lib/paper_trail_diff/recorded_class.rb +14 -19
  80. data/lib/paper_trail_diff/recorded_columns.rb +33 -0
  81. data/lib/paper_trail_diff/root_version_plan.rb +20 -22
  82. data/lib/paper_trail_diff/root_version_selection.rb +39 -29
  83. data/lib/paper_trail_diff/scope_condition.rb +7 -17
  84. data/lib/paper_trail_diff/scope_ranking.rb +16 -22
  85. data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
  86. data/lib/paper_trail_diff/scoped_analysis_builder.rb +4 -3
  87. data/lib/paper_trail_diff/scoped_root_selection.rb +60 -41
  88. data/lib/paper_trail_diff/snapshot_normalizer.rb +18 -3
  89. data/lib/paper_trail_diff/stored_json_values.rb +52 -0
  90. data/lib/paper_trail_diff/stored_time_precision.rb +30 -18
  91. data/lib/paper_trail_diff/stored_values.rb +20 -0
  92. data/lib/paper_trail_diff/support.rb +185 -35
  93. data/lib/paper_trail_diff/time_of_day.rb +39 -0
  94. data/lib/paper_trail_diff/time_range.rb +37 -20
  95. data/lib/paper_trail_diff/time_version_range.rb +5 -10
  96. data/lib/paper_trail_diff/timeline_builder.rb +3 -3
  97. data/lib/paper_trail_diff/timeline_range.rb +18 -12
  98. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +1 -1
  99. data/lib/paper_trail_diff/total_order.rb +55 -0
  100. data/lib/paper_trail_diff/transaction_cut.rb +192 -91
  101. data/lib/paper_trail_diff/traversal_preparer.rb +5 -8
  102. data/lib/paper_trail_diff/value_objects.rb +8 -4
  103. data/lib/paper_trail_diff/version.rb +1 -1
  104. data/lib/paper_trail_diff/version_association_candidate_scope.rb +1 -12
  105. data/lib/paper_trail_diff/version_boundary.rb +37 -21
  106. data/lib/paper_trail_diff/version_query.rb +25 -25
  107. data/lib/paper_trail_diff/version_range.rb +12 -16
  108. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +32 -0
  109. data/lib/paper_trail_diff/version_table.rb +12 -8
  110. data/lib/paper_trail_diff.rb +28 -42
  111. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +0 -8
  112. data/sig/generated/paper_trail_diff/activity_boundary.rbs +39 -17
  113. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +19 -22
  114. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +0 -5
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -9
  116. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +6 -34
  117. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +11 -4
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +0 -3
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +54 -19
  120. data/sig/generated/paper_trail_diff/activity_range.rbs +6 -20
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +36 -2
  122. data/sig/generated/paper_trail_diff/activity_root_steps.rbs +6 -6
  123. data/sig/generated/paper_trail_diff/activity_scope_filter.rbs +51 -0
  124. data/sig/generated/paper_trail_diff/activity_snapshot_delta.rbs +5 -3
  125. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +21 -3
  126. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +19 -24
  127. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +121 -127
  128. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +41 -8
  129. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +42 -35
  130. data/sig/generated/paper_trail_diff/activity_view.rbs +16 -8
  131. data/sig/generated/paper_trail_diff/analysis.rbs +15 -6
  132. data/sig/generated/paper_trail_diff/analysis_batch.rbs +6 -24
  133. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +0 -13
  134. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +6 -9
  135. data/sig/generated/paper_trail_diff/association_discovery.rbs +0 -3
  136. data/sig/generated/paper_trail_diff/association_key.rbs +5 -0
  137. data/sig/generated/paper_trail_diff/association_traversal.rbs +26 -2
  138. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +17 -17
  139. data/sig/generated/paper_trail_diff/batch_preload.rbs +0 -4
  140. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +47 -0
  141. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -8
  142. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +10 -6
  143. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +11 -5
  144. data/sig/generated/paper_trail_diff/change_attribution.rbs +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 -12
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +0 -2
  148. data/sig/generated/paper_trail_diff/deprecation.rbs +4 -24
  149. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +4 -0
  150. data/sig/generated/paper_trail_diff/endpoint.rbs +40 -16
  151. data/sig/generated/paper_trail_diff/errors.rbs +2 -11
  152. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +2 -1
  153. data/sig/generated/paper_trail_diff/historical_filter.rbs +20 -9
  154. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +40 -10
  155. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -3
  156. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +3 -0
  157. data/sig/generated/paper_trail_diff/live_endpoint_provider.rbs +5 -8
  158. data/sig/generated/paper_trail_diff/live_graph_collector.rbs +2 -2
  159. data/sig/generated/paper_trail_diff/nested_comparator.rbs +20 -4
  160. data/sig/generated/paper_trail_diff/net_change.rbs +168 -0
  161. data/sig/generated/paper_trail_diff/own_window.rbs +22 -0
  162. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +9 -6
  163. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +103 -14
  164. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +39 -0
  165. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +18 -35
  166. data/sig/generated/paper_trail_diff/prepared_history.rbs +9 -12
  167. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
  168. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +68 -14
  169. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +12 -0
  170. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +6 -7
  171. data/sig/generated/paper_trail_diff/read_snapshot.rbs +27 -8
  172. data/sig/generated/paper_trail_diff/recorded_changes.rbs +4 -2
  173. data/sig/generated/paper_trail_diff/recorded_changes_reader.rbs +41 -0
  174. data/sig/generated/paper_trail_diff/recorded_class.rbs +7 -6
  175. data/sig/generated/paper_trail_diff/recorded_columns.rbs +21 -0
  176. data/sig/generated/paper_trail_diff/root_version_plan.rbs +8 -4
  177. data/sig/generated/paper_trail_diff/root_version_selection.rbs +27 -13
  178. data/sig/generated/paper_trail_diff/scope_condition.rbs +0 -2
  179. data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -10
  180. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
  181. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +2 -2
  182. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +37 -14
  183. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +7 -0
  184. data/sig/generated/paper_trail_diff/stored_json_values.rbs +35 -0
  185. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +19 -5
  186. data/sig/generated/paper_trail_diff/stored_values.rbs +13 -0
  187. data/sig/generated/paper_trail_diff/support.rbs +120 -23
  188. data/sig/generated/paper_trail_diff/time_of_day.rbs +21 -0
  189. data/sig/generated/paper_trail_diff/time_range.rbs +15 -8
  190. data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
  191. data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -2
  192. data/sig/generated/paper_trail_diff/timeline_range.rbs +12 -7
  193. data/sig/generated/paper_trail_diff/total_order.rbs +32 -0
  194. data/sig/generated/paper_trail_diff/transaction_cut.rbs +111 -52
  195. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +2 -2
  196. data/sig/generated/paper_trail_diff/value_objects.rbs +5 -1
  197. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +0 -7
  198. data/sig/generated/paper_trail_diff/version_boundary.rbs +15 -8
  199. data/sig/generated/paper_trail_diff/version_query.rbs +17 -10
  200. data/sig/generated/paper_trail_diff/version_range.rbs +6 -9
  201. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +13 -0
  202. data/sig/generated/paper_trail_diff/version_table.rbs +3 -0
  203. data/sig/generated/paper_trail_diff.rbs +16 -16
  204. metadata +28 -6
  205. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +0 -60
  206. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +0 -32
@@ -39,7 +39,7 @@ module PaperTrailDiff
39
39
  changes = ActivityEventRecordResolver.new.deserialized_changeset(@version, model_class)
40
40
  return if changes.nil?
41
41
 
42
- value_changes(changes, Array(model_class.primary_key) + ignored)
42
+ value_changes(model_class, changes, Array(model_class.primary_key) + ignored)
43
43
  end
44
44
 
45
45
  private
@@ -68,16 +68,15 @@ module PaperTrailDiff
68
68
  end
69
69
 
70
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
71
+ # Each side is read as a step's diff reads it (see StoredValues), so a
72
+ # value compares equal to the state the change produced.
73
+ #: (untyped, untyped, Array[String]) -> Hash[String, ValueChange]
74
+ def value_changes(model_class, changes, excluded)
75
+ kept = changes.to_h { |name, values| [name.to_s, values] }.except(*excluded)
76
+ from = StoredValues.apply(model_class, kept.transform_values(&:first))
77
+ to = StoredValues.apply(model_class, kept.transform_values(&:last))
78
+ kept.keys.sort.to_h { |key| [key, ValueChange.new(from: from.fetch(key), to: to.fetch(key))] }
79
+ .freeze
81
80
  end
82
81
  end
83
82
  end
@@ -0,0 +1,60 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Decodes what each version recorded at most once per request, and only when
6
+ # a boundary's changes are read. A version many roots share in a batch, such
7
+ # as an author's, is one decode however many steps name it, and a step the
8
+ # caller never reads costs none.
9
+ class RecordedChangesReader
10
+ #: (Array[String]) -> void
11
+ def initialize(ignore)
12
+ @ignore = ignore
13
+ @changes = {} #: Hash[Array[untyped], Hash[String, ValueChange]?]
14
+ @lock = Mutex.new
15
+ end
16
+
17
+ # What `version` recorded, as PaperTrailDiff.recorded_changes returns it.
18
+ #: (untyped) -> Hash[String, ValueChange]?
19
+ def call(version)
20
+ key = Support.row_key(version)
21
+ @lock.synchronize do
22
+ @changes.fetch(key) { @changes[key] = RecordedChanges.call(version, ignore: @ignore) }
23
+ end
24
+ end
25
+
26
+ # @rbs @ignore: Array[String]
27
+ # @rbs @changes: Hash[Array[untyped], Hash[String, ValueChange]?]
28
+ # @rbs @lock: Thread::Mutex
29
+
30
+ # One boundary's recorded changes, read when first asked for. It lets go of
31
+ # the version and the reader once read, so a result keeps only what was
32
+ # decoded, and not the decodes of the whole call.
33
+ class Pending
34
+ #: (RecordedChangesReader, untyped) -> void
35
+ def initialize(reader, version)
36
+ @reader = reader
37
+ @version = version
38
+ @lock = Mutex.new
39
+ end
40
+
41
+ #: () -> Hash[String, ValueChange]?
42
+ def value
43
+ @lock.synchronize do
44
+ reader = @reader
45
+ if reader
46
+ @value = reader.call(@version)
47
+ @reader = nil
48
+ @version = nil
49
+ end
50
+ @value
51
+ end
52
+ end
53
+
54
+ # @rbs @reader: RecordedChangesReader?
55
+ # @rbs @version: untyped
56
+ # @rbs @value: Hash[String, ValueChange]?
57
+ # @rbs @lock: Thread::Mutex
58
+ end
59
+ end
60
+ end
@@ -8,46 +8,41 @@ module PaperTrailDiff
8
8
  # state before the change, or for a create, the value it was created with.
9
9
  # A version that stored neither stays on the base class.
10
10
  module RecordedClass
11
- module_function
12
-
13
11
  #: (untyped) -> untyped
14
- def for(version)
12
+ def self.for(version)
15
13
  model = Endpoint.model_class(version)
16
14
  return model unless sti_base?(model)
17
15
 
18
16
  type = stored_type(version, model).to_s
19
17
  type.empty? ? model : model.sti_class_for(type)
20
- rescue StandardError => e
21
- raise unless subclass_not_found?(e)
18
+ rescue Support.constant('ActiveRecord::SubclassNotFound')
19
+ raise InvalidEndpointError, "cannot resolve endpoint model: #{type}"
20
+ end
22
21
 
23
- raise InvalidEndpointError, "cannot resolve endpoint model: #{type}", cause: e
22
+ # The class a version recorded, or a live record's own class.
23
+ #: (untyped) -> untyped
24
+ def self.of_endpoint(endpoint)
25
+ Endpoint.version?(endpoint) ? self.for(endpoint) : endpoint.class
24
26
  end
25
27
 
26
28
  #: (untyped) -> bool
27
- def sti_base?(model)
28
- model.base_class == model && model.columns_hash.key?(model.inheritance_column.to_s)
29
+ def self.sti_base?(model)
30
+ model.base_class == model && model.columns_hash.key?(model.inheritance_column)
29
31
  end
30
32
  private_class_method :sti_base?
31
33
 
32
34
  #: (untyped, untyped) -> untyped
33
- def stored_type(version, model)
34
- column = model.inheritance_column.to_s
35
+ def self.stored_type(version, model)
36
+ column = model.inheritance_column
35
37
  if version.object
36
38
  attributes = version.object_deserialized
37
39
  return attributes.is_a?(Hash) ? attributes[column] || attributes[column.to_sym] : nil
38
40
  end
39
41
 
40
42
  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
+ values = changes[column] if changes.respond_to?(:key?)
44
+ values.last if values.instance_of?(Array)
43
45
  end
44
46
  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
47
  end
53
48
  end
@@ -0,0 +1,33 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Whether PaperTrail writes a column's changes to `object_changes` whenever
6
+ # a version saves them. Only then does a version that left a column out of
7
+ # its recorded changes show that the column changed without a version.
8
+ #
9
+ # `has_paper_trail ignore:` and `skip:` leave a column out, and `only:`
10
+ # leaves out every column it does not name. Each can also name a column
11
+ # with a condition, read when the version was saved; such a column might
12
+ # have been left out, so it is not counted as recorded either.
13
+ module RecordedColumns
14
+ #: (untyped, String?) -> bool
15
+ def self.recorded?(model_class, name)
16
+ return false unless Support.versioned?(model_class)
17
+
18
+ options = model_class.paper_trail_options
19
+ return false if named?(options.fetch(:ignore), name) || named?(options.fetch(:skip), name)
20
+
21
+ only = options.fetch(:only) #: Array[untyped]
22
+ only.empty? || only.include?(name)
23
+ end
24
+
25
+ # PaperTrail keeps each entry as a name, or as a hash of names to
26
+ # conditions, which may be a subclass such as HashWithIndifferentAccess.
27
+ #: (Array[untyped], String?) -> bool
28
+ def self.named?(entries, name)
29
+ entries.any? { |entry| entry.is_a?(Hash) ? entry.key?(name) : entry == name }
30
+ end
31
+ private_class_method :named?
32
+ end
33
+ end
@@ -44,11 +44,7 @@ module PaperTrailDiff
44
44
  end
45
45
 
46
46
  #: () -> RootVersionPlan
47
- def empty
48
- versions = [] #: Array[untyped]
49
- steps = [] #: Array[[untyped, untyped]]
50
- new(versions: versions, steps: steps)
51
- end
47
+ def empty = closing_on(nil)
52
48
 
53
49
  # No root version to report or replay: only descendants moved, and the
54
50
  # live record is the root's state throughout.
@@ -82,13 +78,12 @@ module PaperTrailDiff
82
78
  end
83
79
 
84
80
  #: () -> RootVersionPlan
85
- def closing_on_destroy
86
- self.class.new(
87
- versions: versions, steps: steps, context_version: context_version,
88
- reconstruction_versions: reconstruction_versions, mutations: mutations,
89
- closing_record: closing_record, closes_on_destroy: true
90
- )
91
- end
81
+ def closing_on_destroy = copy(closes_on_destroy: true)
82
+
83
+ # The same plan reporting only `selected` as mutations, of the versions it
84
+ # holds.
85
+ #: (Array[untyped]) -> RootVersionPlan
86
+ def reporting(selected) = copy(mutations: selected)
92
87
 
93
88
  # What the range's final state is read from, which is the live record when
94
89
  # the window closes on current state and the last version otherwise.
@@ -99,19 +94,28 @@ module PaperTrailDiff
99
94
 
100
95
  #: (untyped) -> bool
101
96
  def mutation?(version)
102
- @mutation_keys.include?(key(version))
97
+ @mutation_keys.include?(Support.row_key(version))
103
98
  end
104
99
 
105
100
  private
106
101
 
107
102
  # @rbs @mutation_keys: Set[Array[untyped]]
108
103
 
104
+ #: (**untyped) -> RootVersionPlan
105
+ def copy(**changes)
106
+ self.class.new(
107
+ versions: versions, steps: steps, context_version: context_version,
108
+ reconstruction_versions: reconstruction_versions, mutations: mutations,
109
+ closing_record: closing_record, closes_on_destroy: closes_on_destroy, **changes
110
+ )
111
+ end
112
+
109
113
  #: () -> Array[untyped]
110
114
  def default_mutations
111
115
  return @versions unless @context_version
112
116
 
113
- context = key(@context_version)
114
- @versions.reject { |version| key(version) == context }
117
+ context = Support.row_key(@context_version)
118
+ @versions.reject { |version| Support.row_key(version) == context }
115
119
  end
116
120
 
117
121
  # A Set only makes the lookup in `mutation?` fast; an Array would answer the
@@ -119,13 +123,7 @@ module PaperTrailDiff
119
123
  # mutant:disable
120
124
  #: (Array[untyped]) -> Set[Array[untyped]]
121
125
  def key_set(versions)
122
- Set.new(versions.map { |version| key(version) })
123
- end
124
-
125
- # By class name, so a version still matches after its class is reloaded.
126
- #: (untyped) -> Array[untyped]
127
- def key(version)
128
- [version.class.name, version.id]
126
+ Set.new(versions.map { |version| Support.row_key(version) })
129
127
  end
130
128
  end
131
129
  end
@@ -9,7 +9,9 @@ module PaperTrailDiff
9
9
  # a filter must never remove it.
10
10
  #
11
11
  # Both the single-record and the batched selectors resolve this here, because
12
- # the rule is subtle enough that two copies of it would drift apart.
12
+ # the rule is subtle enough that two copies of it would drift apart. Their
13
+ # versions are put in order here too, which refuses a sequence that cannot
14
+ # be ordered (see Support.chronological_sort) whichever selector read it.
13
15
  class RootVersionSelection
14
16
  # An error is a specification, so it names the way out as well as the wall.
15
17
  # A window ending at the present can never gain a later version, which makes
@@ -20,17 +22,23 @@ module PaperTrailDiff
20
22
  'final change, and there is no current record to end at: narrow ' \
21
23
  'the window to end before the last recorded version'
22
24
 
23
- #: (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?filtered: bool, ?live_endpoint: untyped) -> void
25
+ # `selected` is what a filter keeps of `in_range`; one that keeps every
26
+ # version is no filter. Activity on associations reports the changes a
27
+ # filter keeps on them wherever they fall in the range, so a `whole` plan
28
+ # replays every root version there, as one without a filter does, and the
29
+ # filter names only which of them are the root's own mutations.
30
+ #: (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?live_endpoint: untyped, ?whole: bool) -> void
24
31
  def initialize( # rubocop:disable Metrics/ParameterLists
25
- in_range:, selected:, after_range:, windowed:, context_required: false, filtered: false,
26
- live_endpoint: nil
32
+ in_range:, selected:, after_range:, windowed:, context_required: false, live_endpoint: nil,
33
+ whole: false
27
34
  )
28
- @in_range = in_range
29
- @selected = selected
35
+ @in_range = Support.chronological_sort(in_range)
36
+ @reported = Support.chronological_sort(selected)
37
+ @selected = whole ? @in_range : @reported
30
38
  @after_range = after_range
31
39
  @windowed = windowed
32
40
  @context_required = context_required
33
- @filtered = filtered
41
+ @filtered = @selected.length < @in_range.length
34
42
  @live_endpoint = live_endpoint
35
43
  end
36
44
 
@@ -40,12 +48,14 @@ module PaperTrailDiff
40
48
 
41
49
  closing = revealing_version || @live_endpoint
42
50
  plan = @filtered ? filtered_plan(closing) : contiguous_plan(closing)
43
- closes_on_destroy?(closing) ? plan.closing_on_destroy : plan
51
+ plan = plan.closing_on_destroy if closes_on_destroy?(closing)
52
+ plan.reporting(@reported)
44
53
  end
45
54
 
46
55
  private
47
56
 
48
57
  # @rbs @in_range: Array[untyped]
58
+ # @rbs @reported: Array[untyped]
49
59
  # @rbs @selected: Array[untyped]
50
60
  # @rbs @after_range: untyped
51
61
  # @rbs @windowed: bool
@@ -96,17 +106,15 @@ module PaperTrailDiff
96
106
  filtered_plan_for(steps, revealing)
97
107
  end
98
108
 
109
+ # The steps run in order, and so do the versions they pass.
99
110
  #: (Array[[untyped, untyped]], untyped) -> RootVersionPlan
100
111
  def filtered_plan_for(steps, revealing)
101
112
  live = revealing if Endpoint.record?(revealing)
102
- versions = chronological(
103
- (steps.flatten(1) + closing_versions).reject { |entry| Endpoint.record?(entry) }
104
- )
113
+ versions = (steps.flatten + closing_versions).reject { |entry| Endpoint.record?(entry) }.uniq
105
114
  RootVersionPlan.new(
106
115
  versions: versions, steps: steps,
107
116
  context_version: (revealing unless live),
108
- reconstruction_versions: spanned(versions),
109
- mutations: @selected, closing_record: live
117
+ reconstruction_versions: spanned(versions), closing_record: live
110
118
  )
111
119
  end
112
120
 
@@ -119,30 +127,32 @@ module PaperTrailDiff
119
127
  terminal_destroy? ? [@selected.last] : []
120
128
  end
121
129
 
122
- # Everything the span passes through, filtered out or not. A replay that
123
- # skipped the excluded versions would carry a stale state into the next
124
- # reported step, so the two selected mutations either side of a gap would
125
- # disagree about what the record looked like between them.
126
- #: (Array[untyped]) -> Array[untyped]
130
+ # Everything the span passes through, filtered out or not, through the
131
+ # version that reveals the last selected mutation, which can lie after the
132
+ # range. A replay that skipped the excluded versions would carry a stale
133
+ # state into the next reported step, so the two selected mutations either
134
+ # side of a gap would disagree about what the record looked like between
135
+ # them. One that stopped before the revealing version would read what the
136
+ # last one produced from history that ends before it. Only the version
137
+ # that reveals the last can lie outside the range, and it comes after it.
138
+ # With no versions there is no span, and a plan replays its versions.
139
+ #: (Array[untyped]) -> Array[untyped]?
127
140
  def spanned(versions)
141
+ return if versions.empty?
142
+
128
143
  first = versions.first
129
144
  last = versions.last
130
- return versions unless first && last
131
-
132
- @in_range.select do |candidate|
145
+ (@in_range.select do |candidate|
133
146
  !Support.compare_versions(first, candidate).positive? &&
134
147
  !Support.compare_versions(candidate, last).positive?
135
- end
136
- end
137
-
138
- #: (Array[untyped]) -> Array[untyped]
139
- def chronological(versions)
140
- Support.chronological_sort(versions.uniq { |version| [version.class.name, version.id] })
148
+ end + versions).uniq
141
149
  end
142
150
 
151
+ # The versions in range are in order, so the first one after a version is
152
+ # found by a search rather than by passing every version before it.
143
153
  #: (untyped) -> untyped
144
154
  def immediate_successor(version)
145
- @in_range.find { |candidate| Support.compare_versions(version, candidate).negative? }
155
+ @in_range.bsearch { |candidate| Support.compare_versions(version, candidate).negative? }
146
156
  end
147
157
 
148
158
  # A version left out by a filter is still the state the last selected change
@@ -166,7 +176,7 @@ module PaperTrailDiff
166
176
  # nothing can follow it, so demanding one would reject the range forever.
167
177
  #: () -> bool
168
178
  def terminal_destroy?
169
- @selected.last&.event.to_s == 'destroy'
179
+ @selected.last.event == 'destroy'
170
180
  end
171
181
  end
172
182
  end
@@ -23,7 +23,6 @@ module PaperTrailDiff
23
23
  TEXT_TYPE = 'ActiveModel::Type::ImmutableString'
24
24
  ENUM_TYPE = 'ActiveRecord::Enum::EnumType'
25
25
  BIND_PARAM = 'Arel::Nodes::BindParam'
26
- ATTRIBUTE = 'Arel::Attributes::Attribute'
27
26
  # Adapters that compare strings exactly by default. MySQL and SQL Server
28
27
  # ignore case and trailing spaces by default, which Ruby cannot follow.
29
28
  EXACT_TEXT_ADAPTERS = %w[sqlite3 postgresql].freeze
@@ -41,11 +40,9 @@ module PaperTrailDiff
41
40
  # A through also filters by the scopes of each reflection it passes.
42
41
  #: (untyped) -> bool
43
42
  def self.scoped_path?(reflection)
44
- return !reflection.scope.nil? if reflection.polymorphic?
45
- return true if scoped?(reflection)
46
- return false unless reflection.through_reflection?
47
-
48
- scoped_path?(reflection.through_reflection) || scoped_path?(reflection.source_reflection)
43
+ [reflection, *AssociationTraversal.through_parts(reflection)].any? do |part|
44
+ part.polymorphic? ? !part.scope.nil? : scoped?(part)
45
+ end
49
46
  end
50
47
 
51
48
  # Returns nil when the scope cannot be read as plain conditions and an
@@ -114,11 +111,7 @@ module PaperTrailDiff
114
111
  # a has_one order.
115
112
  #: (untyped) -> bool
116
113
  def self.ranked_parts?(reflection)
117
- return false unless reflection.through_reflection?
118
-
119
- [reflection.through_reflection, reflection.source_reflection].any? do |part|
120
- ranked_part?(part) || ranked_parts?(part)
121
- end
114
+ AssociationTraversal.through_parts(reflection).any? { |part| ranked_part?(part) }
122
115
  end
123
116
 
124
117
  # A polymorphic part's class, and so its scope, is known only per record.
@@ -395,12 +388,9 @@ module PaperTrailDiff
395
388
  # type compares alike.
396
389
  #: (untyped, ?null_test: bool) -> String
397
390
  def column(attribute, null_test: false)
398
- raise Unreadable unless ATTRIBUTE.eql?(attribute.class.name)
399
-
400
- table = attribute.relation
401
- raise Unreadable unless table.name == @model_class.table_name && table.table_alias.nil?
402
-
403
- name = attribute.name
391
+ # Nil for anything but a column of the model's own table, which finds
392
+ # no column below.
393
+ name = ScopeRanking.own_column(attribute, @model_class) #: String
404
394
  column = @model_class.columns_hash[name]
405
395
  raise Unreadable unless column && (null_test || comparable?(name, column))
406
396
 
@@ -47,7 +47,7 @@ module PaperTrailDiff
47
47
  # Returns nil when the ranking cannot be read exactly.
48
48
  #: (untyped, untyped, untyped) -> ScopeRanking?
49
49
  def self.build(relation, reflection, model_class)
50
- return unless own?(reflection) && plain_offset?(relation)
50
+ return unless own?(reflection)
51
51
 
52
52
  keys = keys(relation.order_values, model_class)
53
53
  return unless keys
@@ -55,7 +55,7 @@ module PaperTrailDiff
55
55
  nulls_last = NULLS_LAST[model_class.connection_db_config.adapter]
56
56
  return if nulls_last.nil?
57
57
 
58
- new(model_class, keys, nulls_last, relation.limit_value, relation.offset_value)
58
+ new(model_class, keys, nulls_last, Support.limit(relation), Support.offset(relation))
59
59
  end
60
60
 
61
61
  #: (untyped) -> bool
@@ -64,14 +64,6 @@ module PaperTrailDiff
64
64
  end
65
65
  private_class_method :own?
66
66
 
67
- # Active Record casts a limit to an integer but keeps an offset as given,
68
- # which may be a String or SQL.
69
- #: (untyped) -> bool
70
- def self.plain_offset?(relation)
71
- !relation.offset_value.is_a?(String)
72
- end
73
- private_class_method :plain_offset?
74
-
75
67
  # The order's keys up to the primary key, which makes it total. Keys
76
68
  # after it never decide anything.
77
69
  #: (Array[untyped], untyped) -> Array[[String, bool]]?
@@ -95,18 +87,22 @@ module PaperTrailDiff
95
87
  def self.column(node, model_class)
96
88
  return unless DIRECTIONS.key?(node.class.name)
97
89
 
98
- attribute = node.expr
90
+ name = own_column(node.expr, model_class)
91
+ name if orderable?(model_class, name)
92
+ end
93
+ private_class_method :column
94
+
95
+ # The name an Arel attribute gives a column of the model's own table, not
96
+ # of another table or an alias of its own; nil for anything else.
97
+ #: (untyped, untyped) -> String?
98
+ def self.own_column(attribute, model_class)
99
99
  return unless ATTRIBUTE.eql?(attribute.class.name)
100
100
 
101
101
  table = attribute.relation
102
- return unless table.name == model_class.table_name && table.table_alias.nil?
103
-
104
- name = attribute.name
105
- name if orderable?(model_class, name)
102
+ attribute.name if table.name == model_class.table_name && table.table_alias.nil?
106
103
  end
107
- private_class_method :column
108
104
 
109
- #: (untyped, String) -> bool
105
+ #: (untyped, String?) -> bool
110
106
  def self.orderable?(model_class, name)
111
107
  return false unless model_class.columns_hash.key?(name)
112
108
 
@@ -146,7 +142,7 @@ module PaperTrailDiff
146
142
  end
147
143
  private_class_method :exact_time?
148
144
 
149
- #: (untyped, Array[[String, bool]], bool, Integer?, Integer?) -> void
145
+ #: (untyped, Array[[String, bool]], bool, Integer?, Integer) -> void
150
146
  def initialize(model_class, keys, nulls_last, limit, offset)
151
147
  @model_class = model_class
152
148
  @keys = keys
@@ -159,10 +155,8 @@ module PaperTrailDiff
159
155
  # The members among records that met the scope's conditions, in order.
160
156
  #: (Array[untyped]) -> Array[untyped]
161
157
  def call(records)
162
- offset = @offset
163
158
  limit = @limit
164
- ranked = records.sort_by { |record| sort_key(record.attributes) }
165
- ranked = ranked.drop(offset) if offset
159
+ ranked = records.sort_by { |record| sort_key(record.attributes) }.drop(@offset)
166
160
  limit ? ranked.first(limit) : ranked
167
161
  end
168
162
 
@@ -172,7 +166,7 @@ module PaperTrailDiff
172
166
  # @rbs @keys: Array[[String, bool]]
173
167
  # @rbs @nulls_last: bool
174
168
  # @rbs @limit: Integer?
175
- # @rbs @offset: Integer?
169
+ # @rbs @offset: Integer
176
170
 
177
171
  # Keys compare in turn, and the primary key always decides. A descending
178
172
  # key negates its places, which also moves NULL to the other end, as each
@@ -41,10 +41,23 @@ module PaperTrailDiff
41
41
  # without destroy history has no rows and is left out.
42
42
  #: () -> Hash[Array[String], Array[ChangeRow]]
43
43
  def change_rows
44
- rows = {} #: Hash[Array[String], Array[ChangeRow]]
45
- analyses.each { |identity, analysis| rows[identity] = analysis.change_rows }
46
- deleted.each { |identity, analysis| rows[identity] = analysis.change_rows if analysis }
47
- rows.freeze
44
+ each_root(&:change_rows)
45
+ end
46
+
47
+ # The analysis of one of `roots`, found from the record itself. The keys
48
+ # are its base class's name and its ID as a string, which a subclass or an
49
+ # integer ID gets wrong when built by hand. Raises KeyError for a record
50
+ # the selection did not load; a deleted root's analysis is in `deleted`.
51
+ #: (untyped) -> Analysis
52
+ def analysis_for(record)
53
+ analyses.fetch(Endpoint.identity(record))
54
+ end
55
+
56
+ # Each root's net changes, keyed as `change_rows` is; the block picks the
57
+ # rows to keep, as for Analysis#net_changes.
58
+ #: () ?{ (ChangeRow) -> boolish } -> Hash[Array[String], Array[NetChange]]
59
+ def net_changes(&keep)
60
+ each_root { |analysis| analysis.net_changes(&keep) }
48
61
  end
49
62
 
50
63
  # Two elements, not three: `roots` is reached by name so that existing
@@ -53,5 +66,15 @@ module PaperTrailDiff
53
66
  def to_ary
54
67
  [analyses, unreachable]
55
68
  end
69
+
70
+ private
71
+
72
+ # What the block makes of each root's analysis: the roots that still
73
+ # exist, then the deleted ones that have history to report.
74
+ #: [T] () { (Analysis) -> T } -> Hash[Array[String], T]
75
+ def each_root(&block)
76
+ reported = deleted.filter_map { |identity, analysis| [identity, analysis] if analysis }
77
+ analyses.merge(reported.to_h).transform_values(&block).freeze
78
+ end
56
79
  end
57
80
  end
@@ -4,10 +4,10 @@
4
4
  module PaperTrailDiff
5
5
  # Selects both populations and checks their shared ceiling before analysis.
6
6
  class ScopedAnalysisBuilder
7
- #: (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped, ?activity_tree: AssociationTree?, ?version_scope: untyped) -> void
7
+ #: (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped, ?activity_tree: AssociationTree?, ?version_scope: untyped, ?traversal: AssociationTraversal?) -> void
8
8
  def initialize( # rubocop:disable Metrics/ParameterLists
9
9
  scope, limit:, within:, historical_filter:, max_filter_versions:, include_deleted:,
10
- analyzer:, deleted_analyzer:, activity_tree: nil, version_scope: nil
10
+ analyzer:, deleted_analyzer:, activity_tree: nil, version_scope: nil, traversal: nil
11
11
  )
12
12
  raise ConfigurationError, 'limit: is required when selecting roots by scope' if limit.nil?
13
13
  unless [true, false].include?(include_deleted)
@@ -17,7 +17,8 @@ module PaperTrailDiff
17
17
  @selection = ScopedRootSelection.new(
18
18
  scope, limit: limit, time_range: within.nil? ? nil : TimeRange.new(within),
19
19
  historical_filter: historical_filter, max_filter_versions: max_filter_versions,
20
- activity_tree: activity_tree, version_scope: version_scope
20
+ activity_tree: activity_tree, version_scope: version_scope,
21
+ traversal: traversal
21
22
  )
22
23
  @deleted_filter = deleted_filter(scope, include_deleted)
23
24
  @include_deleted = include_deleted