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,13 +4,13 @@
4
4
  module PaperTrailDiff
5
5
  # Checks the recorded sequence itself, before any question of association
6
6
  # setup: whether the versions can be ordered at all, and whether timestamps
7
- # they share hide changes that ordering alone cannot recover.
7
+ # they share hide changes from a path PT-AT reads.
8
8
  class VersionSequenceDiagnostics
9
- #: (untyped, untyped, ?associations_selected: bool) -> void
10
- def initialize(from_version, to_version, associations_selected: false)
9
+ #: (untyped, untyped, ?fallback_selected: bool) -> void
10
+ def initialize(from_version, to_version, fallback_selected: false)
11
11
  @from_version = from_version
12
12
  @to_version = to_version
13
- @associations_selected = associations_selected
13
+ @fallback_selected = fallback_selected
14
14
  end
15
15
 
16
16
  #: () -> Array[DiagnosticIssue]
@@ -18,7 +18,7 @@ module PaperTrailDiff
18
18
  versions = ordered_range_versions
19
19
  issues = [] #: Array[DiagnosticIssue?]
20
20
  issues << unorderable(versions)
21
- issues << tied_timestamps(versions) if @associations_selected
21
+ issues << tied_timestamps(versions) if @fallback_selected
22
22
  issues.compact
23
23
  rescue StandardError
24
24
  []
@@ -28,7 +28,7 @@ module PaperTrailDiff
28
28
 
29
29
  # @rbs @from_version: untyped
30
30
  # @rbs @to_version: untyped
31
- # @rbs @associations_selected: bool
31
+ # @rbs @fallback_selected: bool
32
32
 
33
33
  # Ordering falls back to the id when timestamps tie, which only recovers the
34
34
  # real sequence for ids that increase with insertion. Reported before a run
@@ -46,11 +46,12 @@ module PaperTrailDiff
46
46
  )
47
47
  end
48
48
 
49
- # Association membership is recorded per version but resolved by timestamp,
50
- # so a tie hides any association change across that pair. Unlike an
51
- # unorderable sequence this is not always wrong: if nothing associated
52
- # changed between them the result is correct, and the gem cannot tell which
53
- # it is, because not seeing the change is the symptom. So it warns.
49
+ # Loaded history orders versions that share a timestamp by id, but PT-AT
50
+ # places association changes by timestamp alone, so a path it reads loses
51
+ # any change between such a pair. Unlike an unorderable sequence this is
52
+ # not always wrong: if nothing that path reaches changed between them the
53
+ # result is correct, and the gem cannot tell which it is, because not
54
+ # seeing the change is the symptom. So it warns.
54
55
  #: (Array[untyped]) -> DiagnosticIssue?
55
56
  def tied_timestamps(versions)
56
57
  pair = Support.tied_timestamp_pair(versions)
@@ -61,22 +62,36 @@ module PaperTrailDiff
61
62
  severity: :warning,
62
63
  code: :tied_version_timestamps,
63
64
  message: "versions #{left.id.inspect} and #{right.id.inspect} share the timestamp " \
64
- "#{left.created_at.inspect}, so association changes between them cannot " \
65
- 'be detected; record versions at sub-second precision to separate them',
65
+ "#{left.created_at.inspect}, and an association requested here is read with " \
66
+ 'PT-AT, which places association changes by timestamp alone, so a change ' \
67
+ 'between them can be missed; record versions at sub-second precision to ' \
68
+ 'separate them',
66
69
  version_id: left.id
67
70
  )
68
71
  end
69
72
 
70
73
  #: () -> Array[untyped]
71
74
  def ordered_range_versions
72
- bounds = [@from_version.created_at, @to_version.created_at].compact.sort
73
- return [] unless bounds.length == 2
75
+ range = time_range
76
+ return [] unless range
74
77
 
75
78
  @from_version.class
76
79
  .where(item_type: @from_version.item_type, item_id: @from_version.item_id)
77
- .where(created_at: bounds.first..bounds.last)
80
+ .where(created_at: range)
78
81
  .to_a
79
82
  .sort_by { |version| Support.chronological_version_key(version) }
80
83
  end
84
+
85
+ # Between the two versions, in either order, or from the one version on
86
+ # when the other endpoint is the current record. A version that recorded
87
+ # no time bounds nothing.
88
+ #: () -> Range[untyped]?
89
+ def time_range
90
+ from = @from_version.created_at
91
+ return from && (from..) unless @to_version
92
+
93
+ bounds = [from, @to_version.created_at].compact.sort
94
+ bounds.first..bounds.last if bounds.length == 2
95
+ end
81
96
  end
82
97
  end
@@ -0,0 +1,60 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # PT-AT reads an association's history from its owner's version tables: it
6
+ # looks for a child's versions in the owner's version table, and numbers a
7
+ # transaction by the first version saved in it, in whichever table. A model
8
+ # whose versions, or version associations, live in another table than its
9
+ # owner's would read other records' versions or none, so it is refused.
10
+ module VersionTable
11
+ # Why the association, or a part of a through, cannot be read across
12
+ # version tables.
13
+ #: (untyped) -> String?
14
+ def self.unsupported_reason(reflection)
15
+ part = separate_part(reflection)
16
+ return unless part
17
+
18
+ "#{part.active_record.name}##{part.name} keeps versions in #{tables(part.active_record)} " \
19
+ "but #{part.klass.name} in #{tables(part.klass)}, and association history is read " \
20
+ 'from one set of version tables'
21
+ end
22
+
23
+ # The reflection, or the first part of a through, whose ends keep versions
24
+ # in different tables. A polymorphic belongs_to names no single target,
25
+ # and an unversioned target has no history to compare.
26
+ #: (untyped) -> untyped
27
+ def self.separate_part(reflection)
28
+ if reflection.through_reflection?
29
+ return [reflection.through_reflection, reflection.source_reflection].filter_map do |part|
30
+ separate_part(part)
31
+ end.first
32
+ end
33
+ return if reflection.polymorphic?
34
+
35
+ owner = reflection.active_record
36
+ target = reflection.klass
37
+ return unless Support.versioned?(owner) && Support.versioned?(target)
38
+
39
+ reflection unless tables(owner) == tables(target)
40
+ end
41
+ private_class_method :separate_part
42
+
43
+ # PT-AT's version association rows joined to the versions they were saved
44
+ # with. Its `belongs_to :version` names PaperTrail's default class whatever
45
+ # table a model's versions are in, so the join names the table instead.
46
+ #: (untyped, untyped) -> untyped
47
+ def self.joined(associations, versions)
48
+ rows = associations.arel_table
49
+ table = versions.arel_table
50
+ associations.joins(rows.join(table).on(table[:id].eq(rows[:version_id])).join_sources)
51
+ end
52
+
53
+ #: (untyped) -> String
54
+ def self.tables(model)
55
+ history = model.paper_trail
56
+ "#{history.version_class.table_name} and #{history.version_association_class.table_name}"
57
+ end
58
+ private_class_method :tables
59
+ end
60
+ end
@@ -9,11 +9,18 @@ require_relative 'paper_trail_diff/version_query'
9
9
  require_relative 'paper_trail_diff/stored_time_precision'
10
10
  require_relative 'paper_trail_diff/version_boundary'
11
11
  require_relative 'paper_trail_diff/instrumentation'
12
+ require_relative 'paper_trail_diff/deprecation'
12
13
  require_relative 'paper_trail_diff/errors'
13
14
  require_relative 'paper_trail_diff/configuration'
14
15
  require_relative 'paper_trail_diff/endpoint'
16
+ require_relative 'paper_trail_diff/recorded_class'
17
+ require_relative 'paper_trail_diff/association_key'
18
+ require_relative 'paper_trail_diff/version_table'
15
19
  require_relative 'paper_trail_diff/association_traversal'
16
- require_relative 'paper_trail_diff/batch_safety'
20
+ require_relative 'paper_trail_diff/scope_ranking'
21
+ require_relative 'paper_trail_diff/scope_condition'
22
+ require_relative 'paper_trail_diff/approximate_paths'
23
+ require_relative 'paper_trail_diff/fallback_paths'
17
24
  require_relative 'paper_trail_diff/traversal_preparer'
18
25
  require_relative 'paper_trail_diff/association_discovery'
19
26
  require_relative 'paper_trail_diff/diagnostics'
@@ -27,9 +34,11 @@ require_relative 'paper_trail_diff/traversal_emitter'
27
34
  require_relative 'paper_trail_diff/snapshot_traversal'
28
35
  require_relative 'paper_trail_diff/association_diff_traversal'
29
36
  require_relative 'paper_trail_diff/traversal'
37
+ require_relative 'paper_trail_diff/change_row'
30
38
  require_relative 'paper_trail_diff/collection_comparator'
31
39
  require_relative 'paper_trail_diff/nested_comparator'
32
40
  require_relative 'paper_trail_diff/engine'
41
+ require_relative 'paper_trail_diff/habtm_transaction_owners'
33
42
  require_relative 'paper_trail_diff/historical_association_reifier'
34
43
  require_relative 'paper_trail_diff/prepared_record_index'
35
44
  require_relative 'paper_trail_diff/direct_record_state_loader'
@@ -42,6 +51,7 @@ require_relative 'paper_trail_diff/prepared_edge_loader'
42
51
  require_relative 'paper_trail_diff/prepared_history_loader'
43
52
  require_relative 'paper_trail_diff/prepared_association_reifier'
44
53
  require_relative 'paper_trail_diff/live_association_reader'
54
+ require_relative 'paper_trail_diff/batch_preload'
45
55
  require_relative 'paper_trail_diff/live_endpoint_batch_loader'
46
56
  require_relative 'paper_trail_diff/preloaded_endpoint_batch_loader'
47
57
  require_relative 'paper_trail_diff/live_endpoint_provider'
@@ -56,6 +66,7 @@ require_relative 'paper_trail_diff/snapshot_normalizer'
56
66
  require_relative 'paper_trail_diff/historical_snapshot_store'
57
67
  require_relative 'paper_trail_diff/timeline_snapshot_provider'
58
68
  require_relative 'paper_trail_diff/activity_event_record_resolver'
69
+ require_relative 'paper_trail_diff/recorded_changes'
59
70
  require_relative 'paper_trail_diff/activity_event_route_finder'
60
71
  require_relative 'paper_trail_diff/activity_relationship'
61
72
  require_relative 'paper_trail_diff/activity_collection_route_change'
@@ -68,7 +79,7 @@ require_relative 'paper_trail_diff/activity_event_snapshot_refresher'
68
79
  require_relative 'paper_trail_diff/activity_root_snapshot_refresher'
69
80
  require_relative 'paper_trail_diff/branch_snapshot_refresher'
70
81
  require_relative 'paper_trail_diff/activity_boundary'
71
- require_relative 'paper_trail_diff/activity_grouping'
82
+ require_relative 'paper_trail_diff/activity_view'
72
83
  require_relative 'paper_trail_diff/activity_transaction_grouper'
73
84
  require_relative 'paper_trail_diff/step'
74
85
  require_relative 'paper_trail_diff/analysis'
@@ -77,22 +88,27 @@ require_relative 'paper_trail_diff/analysis_batch'
77
88
  require_relative 'paper_trail_diff/deleted_analysis_batch'
78
89
  require_relative 'paper_trail_diff/scoped_analysis'
79
90
  require_relative 'paper_trail_diff/historical_filter'
91
+ require_relative 'paper_trail_diff/association_activity_edge'
92
+ require_relative 'paper_trail_diff/association_activity_selection'
80
93
  require_relative 'paper_trail_diff/scoped_root_selection'
94
+ require_relative 'paper_trail_diff/deleted_root_filter'
81
95
  require_relative 'paper_trail_diff/scoped_analysis_builder'
82
96
  require_relative 'paper_trail_diff/batched_root_analyzer'
83
97
  require_relative 'paper_trail_diff/version_range'
84
98
  require_relative 'paper_trail_diff/version_sequence_diagnostics'
85
99
  require_relative 'paper_trail_diff/time_range'
100
+ require_relative 'paper_trail_diff/transaction_cut'
86
101
  require_relative 'paper_trail_diff/time_version_range'
87
102
  require_relative 'paper_trail_diff/timeline_range'
88
103
  require_relative 'paper_trail_diff/timeline_builder'
89
104
  require_relative 'paper_trail_diff/activity_range'
90
105
  require_relative 'paper_trail_diff/activity_event'
91
106
  require_relative 'paper_trail_diff/activity_child_candidate_loader'
107
+ require_relative 'paper_trail_diff/activity_target_candidate_loader'
92
108
  require_relative 'paper_trail_diff/activity_version_collector'
93
109
  require_relative 'paper_trail_diff/activity_snapshot_sequence'
110
+ require_relative 'paper_trail_diff/activity_tree_filter'
94
111
  require_relative 'paper_trail_diff/activity_history'
95
- require_relative 'paper_trail_diff/time_activity_timeline_builder'
96
112
  require_relative 'paper_trail_diff/activity_timeline_builder'
97
113
  require_relative 'paper_trail_diff/paper_trail_adapter'
98
114
 
@@ -110,10 +126,10 @@ require_relative 'paper_trail_diff/paper_trail_adapter'
110
126
  # type comparison_input = Hash[String | Symbol, untyped]
111
127
  # type comparison_results = Hash[identity, Diff]
112
128
  # type report_options = {
113
- # within: untyped, activity: bool, version_scope: untyped,
114
- # close_on: Symbol?, snapshots: bool, group: Symbol?
129
+ # within: untyped, activity: bool, version_scope: untyped, view: ActivityView
115
130
  # }
116
131
  # type ignore_option = Array[String | Symbol] | Hash[String | Symbol, untyped]
132
+ # type association_option = String | Symbol | Array[untyped] | Hash[untyped, untyped]
117
133
  # type reference_key = :type | :id | "type" | "id"
118
134
  # type traversal_context = :change | :included_state
119
135
  # type traversal_state = :before | :after
@@ -134,43 +150,45 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
134
150
 
135
151
  class << self # rubocop:disable Metrics/ClassLength
136
152
  # Compares net state between explicit PaperTrail-version or current-record endpoints.
137
- #: (untyped, untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> Diff
138
- def compare(
153
+ #: (untyped, untyped, ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?allow_approximate: bool) -> Diff
154
+ def compare( # rubocop:disable Metrics/ParameterLists
139
155
  from_version,
140
156
  to_version,
141
157
  associations: [],
142
158
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
143
- reload_live_endpoints: true
159
+ reload_live_endpoints: nil,
160
+ allow_approximate: false
144
161
  )
145
162
  PaperTrailAdapter.new(
146
163
  associations: associations,
147
164
  ignore: ignore,
148
- reload_live_endpoints: reload_live_endpoints
149
- ).compare(
150
- from_version,
151
- to_version
152
- )
165
+ reload_live_endpoints: Deprecation.reload_live_endpoints!(reload_live_endpoints),
166
+ allow_approximate: allow_approximate
167
+ ).compare(from_version, to_version)
153
168
  end
154
169
 
155
170
  # Compares many independent endpoint pairs while batching current-record loading.
156
- #: (Array[comparison_input], ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?allow_expensive: bool) -> comparison_results
157
- def compare_many(
171
+ #: (Array[comparison_input], ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?allow_expensive: bool?, ?allow_approximate: bool) -> comparison_results
172
+ def compare_many( # rubocop:disable Metrics/ParameterLists
158
173
  comparisons,
159
174
  associations: [],
160
175
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
161
- reload_live_endpoints: true,
162
- allow_expensive: false
176
+ reload_live_endpoints: nil,
177
+ allow_expensive: nil,
178
+ allow_approximate: false
163
179
  )
180
+ Deprecation.allow_expensive!(allow_expensive)
164
181
  PaperTrailAdapter.new(
165
182
  associations: associations,
166
183
  ignore: ignore,
167
- reload_live_endpoints: reload_live_endpoints, allow_expensive: allow_expensive
184
+ reload_live_endpoints: Deprecation.reload_live_endpoints!(reload_live_endpoints),
185
+ allow_approximate: allow_approximate
168
186
  ).compare_many(comparisons)
169
187
  end
170
188
 
171
189
  # Compares every adjacent reconstructed state in an inclusive version range,
172
190
  # by default the record's whole history through its current state.
173
- #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?version_scope: untyped, ?close_on: Symbol?) -> Array[Step]
191
+ #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?close_on: Symbol?, ?allow_approximate: bool) -> Array[Step]
174
192
  def timeline( # rubocop:disable Metrics/ParameterLists
175
193
  record,
176
194
  from: nil,
@@ -179,23 +197,23 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
179
197
  associations: [],
180
198
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
181
199
  version_scope: nil,
182
- close_on: nil
200
+ close_on: nil,
201
+ allow_approximate: false
183
202
  )
184
- PaperTrailAdapter.new(associations: associations, ignore: ignore).timeline(
203
+ Deprecation.close_on!(close_on, within)
204
+ PaperTrailAdapter.new(
205
+ associations: associations, ignore: ignore, allow_approximate: allow_approximate
206
+ ).timeline(
185
207
  record,
186
208
  from: from,
187
209
  to: to,
188
210
  within: within,
189
- version_scope: version_scope,
190
- close_on: close_on
211
+ version_scope: version_scope
191
212
  )
192
213
  end
193
214
 
194
215
  # Compares adjacent root and selected-descendant activity boundaries.
195
- # `reload_live_endpoints:` applies whenever the range ends at the current
196
- # record: an explicit `to:` record, the default range, or a window with no
197
- # later version.
198
- #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
216
+ #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Array[ActivityStep]
199
217
  def activity_timeline( # rubocop:disable Metrics/ParameterLists
200
218
  record,
201
219
  from: nil,
@@ -203,30 +221,32 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
203
221
  within: nil,
204
222
  associations: [],
205
223
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
206
- reload_live_endpoints: true,
224
+ reload_live_endpoints: nil,
207
225
  version_scope: nil,
208
226
  close_on: nil,
209
227
  snapshots: false,
210
- group: nil
228
+ group: nil,
229
+ recorded_changes: false,
230
+ allow_approximate: false
211
231
  )
232
+ Deprecation.close_on!(close_on, within)
212
233
  PaperTrailAdapter.new(
213
- associations: associations,
214
- ignore: ignore,
215
- reload_live_endpoints: reload_live_endpoints
234
+ associations: associations, ignore: ignore,
235
+ reload_live_endpoints: Deprecation.reload_live_endpoints!(reload_live_endpoints),
236
+ recorded_changes: recorded_changes, allow_approximate: allow_approximate
216
237
  ).activity_timeline(
217
238
  record,
218
239
  from: from,
219
240
  to: to,
220
241
  within: within,
221
242
  version_scope: version_scope,
222
- close_on: close_on,
223
243
  group: group,
224
244
  snapshots: snapshots
225
245
  )
226
246
  end
227
247
 
228
248
  # Builds an endpoint diff and root-checkpoint timeline while normalizing each version once.
229
- #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Analysis
249
+ #: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Analysis
230
250
  def analyze( # rubocop:disable Metrics/ParameterLists
231
251
  record,
232
252
  from: nil,
@@ -238,16 +258,21 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
238
258
  version_scope: nil,
239
259
  close_on: nil,
240
260
  snapshots: false,
241
- group: nil
261
+ group: nil,
262
+ recorded_changes: false,
263
+ allow_approximate: false
242
264
  )
243
- PaperTrailAdapter.new(associations: associations, ignore: ignore).analyze(
265
+ Deprecation.close_on!(close_on, within)
266
+ PaperTrailAdapter.new(
267
+ associations: associations, ignore: ignore, recorded_changes: recorded_changes,
268
+ allow_approximate: allow_approximate
269
+ ).analyze(
244
270
  record,
245
271
  from: from,
246
272
  to: to,
247
273
  within: within,
248
274
  activity: activity,
249
275
  version_scope: version_scope,
250
- close_on: close_on,
251
276
  snapshots: snapshots,
252
277
  group: group
253
278
  )
@@ -258,7 +283,7 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
258
283
  # returns a frozen Hash keyed by identity. Roots with nothing to report in
259
284
  # the window return an empty `Analysis`. To let a relation choose the
260
285
  # records, use `analyze_scope`.
261
- #: (Array[untyped], ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?allow_expensive: bool) -> Hash[identity, Analysis]
286
+ #: (Array[untyped], ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> Hash[identity, Analysis]
262
287
  def analyze_many( # rubocop:disable Metrics/ParameterLists
263
288
  records,
264
289
  within: nil,
@@ -269,16 +294,23 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
269
294
  close_on: nil,
270
295
  snapshots: false,
271
296
  group: nil,
272
- allow_expensive: false
297
+ allow_expensive: nil,
298
+ recorded_changes: false,
299
+ allow_approximate: false
273
300
  )
301
+ Deprecation.close_on!(close_on, within)
302
+ Deprecation.allow_expensive!(allow_expensive)
274
303
  PaperTrailAdapter.new(
275
- associations: associations, ignore: ignore, allow_expensive: allow_expensive
304
+ associations: associations, ignore: ignore,
305
+ recorded_changes: recorded_changes, allow_approximate: allow_approximate
276
306
  ).analyze_many(records, within: within, activity: activity, version_scope: version_scope,
277
- close_on: close_on, snapshots: snapshots, group: group)
307
+ snapshots: snapshots, group: group)
278
308
  end
279
309
 
280
310
  # Analyzes every root the relation reaches whose history moved inside the
281
- # window. Joined duplicates are read in bounded pages and analyzed once.
311
+ # window. With `activity: true`, a change to a record on one of the
312
+ # requested association paths also counts, because the activity timeline
313
+ # reports it. Joined duplicates are read in bounded pages and analyzed once.
282
314
  #
283
315
  # `limit:` is required and exceeding it raises. Selection moves into the gem
284
316
  # here. The relation's own limit/offset select the live page; this separate
@@ -301,7 +333,7 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
301
333
  # Note also that a relation selects on current state, not on state during
302
334
  # the window: `where(status: 'published')` means published *now*, which is a
303
335
  # different set from what was published while the window was open.
304
- #: (untyped, limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool, ?allow_expensive: bool) -> ScopedAnalysis
336
+ #: (untyped, limit: Integer?, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
305
337
  def analyze_scope( # rubocop:disable Metrics/ParameterLists
306
338
  scope,
307
339
  limit:,
@@ -316,36 +348,56 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
316
348
  historical_filter: nil,
317
349
  max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT,
318
350
  include_deleted: false,
319
- allow_expensive: false
351
+ allow_expensive: nil,
352
+ recorded_changes: false,
353
+ allow_approximate: false
320
354
  )
355
+ Deprecation.close_on!(close_on, within)
356
+ Deprecation.allow_expensive!(allow_expensive)
321
357
  adapter = PaperTrailAdapter.new(associations: associations, ignore: ignore,
322
- allow_expensive: allow_expensive)
358
+ recorded_changes: recorded_changes,
359
+ allow_approximate: allow_approximate)
323
360
  adapter.analyze_scope(
324
361
  scope, limit: limit, within: within, activity: activity,
325
- version_scope: version_scope, close_on: close_on, snapshots: snapshots, group: group,
362
+ version_scope: version_scope, snapshots: snapshots, group: group,
326
363
  historical_filter: historical_filter, max_filter_versions: max_filter_versions,
327
364
  include_deleted: include_deleted
328
365
  )
329
366
  end
330
367
 
331
- # Recent root and selected-child activity through the current saved state.
368
+ # Recent root and selected-child activity through the current saved state,
369
+ # for every root that changed or whose requested associations did.
332
370
  # Historical windows remain explicit on analyze_scope; this entry point is
333
371
  # deliberately named for a report through now rather than an as-of query.
334
- #: (untyped, since: untyped, limit: Integer, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?allow_expensive: bool) -> ScopedAnalysis
372
+ #: (untyped, since: untyped, limit: Integer, ?associations: association_option, ?ignore: ignore_option, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
335
373
  def report( # rubocop:disable Metrics/ParameterLists
336
374
  scope, since:, limit:, associations: [], ignore: DEFAULT_IGNORED_ATTRIBUTES,
337
375
  snapshots: false, group: nil, include_deleted: false, historical_filter: nil,
338
- max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, allow_expensive: false
376
+ max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, allow_expensive: nil,
377
+ recorded_changes: false, allow_approximate: false
339
378
  )
379
+ # A range here would become the start of another range.
380
+ if since.nil? || since.is_a?(Range)
381
+ raise InvalidTimeRangeError, '`since` must be a time, date, or string; for a range, ' \
382
+ 'pass it as `within:` to analyze_scope'
383
+ end
384
+
340
385
  analyze_scope(
341
386
  scope,
342
387
  within: since..Time.now.utc, limit: limit, associations: associations,
343
- ignore: ignore, activity: true, close_on: :current, snapshots: snapshots, group: group,
388
+ ignore: ignore, activity: true, snapshots: snapshots, group: group,
344
389
  include_deleted: include_deleted, historical_filter: historical_filter,
345
- max_filter_versions: max_filter_versions, allow_expensive: allow_expensive
390
+ max_filter_versions: max_filter_versions, allow_expensive: allow_expensive,
391
+ recorded_changes: recorded_changes, allow_approximate: allow_approximate
346
392
  )
347
393
  end
348
394
 
395
+ # Warns about deprecated options; see Deprecation.
396
+ #: () -> untyped
397
+ def deprecator
398
+ Deprecation.deprecator
399
+ end
400
+
349
401
  # Returns the association macros this release can normalize.
350
402
  #: () -> Array[Symbol]
351
403
  def supported_association_macros
@@ -358,10 +410,13 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
358
410
  AssociationDiscovery.new(model_or_record, max_depth: max_depth).call
359
411
  end
360
412
 
361
- # Reports known reconstruction hazards without mutating application state.
362
- #: (untyped, untyped, ?associations: Array[String | Symbol]) -> DiagnosticReport
363
- def diagnose(from_version, to_version, associations: [])
364
- HistoryDiagnostics.new(from_version, to_version, associations: associations).call
413
+ # Reports known reconstruction hazards without mutating application state,
414
+ # for the endpoints `compare` takes: two versions, or a version and the
415
+ # current record. Every reason `compare` would refuse them is an error.
416
+ #: (untyped, untyped, ?associations: association_option, ?allow_approximate: bool) -> DiagnosticReport
417
+ def diagnose(from, to, associations: [], allow_approximate: false)
418
+ HistoryDiagnostics.new(from, to, associations: associations,
419
+ allow_approximate: allow_approximate).call
365
420
  end
366
421
 
367
422
  # Looks inside an attribute the database stores whole, such as a JSON or
@@ -390,5 +445,21 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
390
445
 
391
446
  NestedComparator.call(change, to_value)
392
447
  end
448
+
449
+ # Reads what PaperTrail recorded with one version: its `object_changes`,
450
+ # typed by the version's model, as `{ "title" => <from "Draft" to "Published"> }`.
451
+ # Activity methods read it for every step source with `recorded_changes: true`.
452
+ #
453
+ # A step's diff compares the states before and after an event, so it also
454
+ # includes anything saved without a version in between; this does not.
455
+ # Returns nil when nothing was recorded (no `object_changes` column, or no
456
+ # value for this version), which differs from a recorded empty hash. Unlike
457
+ # PaperTrail's `version.changeset`, it never loads the record, so it costs no
458
+ # query per version and still types a deleted record's changes. `ignore:`
459
+ # takes attribute names, as an array, and defaults to `updated_at`.
460
+ #: (untyped, ?ignore: Array[String | Symbol]) -> Hash[String, ValueChange]?
461
+ def recorded_changes(version, ignore: DEFAULT_IGNORED_ATTRIBUTES)
462
+ RecordedChanges.call(version, ignore: ignore)
463
+ end
393
464
  end
394
465
  end
@@ -17,6 +17,11 @@ module PaperTrailDiff
17
17
 
18
18
  @route_finder: ActivityEventRouteFinder
19
19
 
20
+ # An edit can move a target into or out of a scope, which a replacement
21
+ # in place cannot show, so a scoped route's branch is read again instead.
22
+ # : (Array[Array[untyped]]) -> bool
23
+ def scoped_route?: (Array[Array[untyped]]) -> bool
24
+
20
25
  # : (Array[untyped], untyped, SnapshotNormalizer, untyped, untyped) -> RecordSnapshot?
21
26
  def normalized_route_record: (Array[untyped], untyped, SnapshotNormalizer, untyped, untyped) -> RecordSnapshot?
22
27
 
@@ -29,8 +34,11 @@ module PaperTrailDiff
29
34
  # : (Array[RecordSnapshot], untyped, RecordSnapshot?) -> [Array[RecordSnapshot], bool]
30
35
  def replace_existing_target: (Array[RecordSnapshot], untyped, RecordSnapshot?) -> [ Array[RecordSnapshot], bool ]
31
36
 
32
- # : (untyped, RecordSnapshot?) -> String
33
- def replacement_type: (untyped, RecordSnapshot?) -> String
37
+ # The target is matched by id within its table rather than by type name.
38
+ # Without `item_subtype`, a version names only the STI base class, and a
39
+ # row whose type changes is replaced by a record of another class.
40
+ # : (RecordSnapshot, untyped) -> bool
41
+ def same_table?: (RecordSnapshot, untyped) -> bool
34
42
 
35
43
  # : (untyped) -> untyped
36
44
  def endpoint_model_class: (untyped) -> untyped