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,11 +4,15 @@
4
4
  module PaperTrailDiff
5
5
  # Analyzes missing roots together without pretending that they have live rows.
6
6
  class DeletedAnalysisBatch
7
- #: (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, ?version_scope: untyped) -> void
7
+ # `context_required` reads a root that did not change in the window from
8
+ # the version after it, so its associations' activity can be reported.
9
+ #: (untyped, identities: Array[Array[String]], time_range: TimeRange?, analyzer: untyped, history_preparer: untyped, version_scope: untyped, context_required: bool) -> void
8
10
  def initialize( # rubocop:disable Metrics/ParameterLists
9
- model, identities:, time_range:, analyzer:, history_preparer:, version_scope: nil
11
+ model, identities:, time_range:, analyzer:, history_preparer:, version_scope:,
12
+ context_required:
10
13
  )
11
14
  @model = model
15
+ @context_required = context_required
12
16
  @identities = identities
13
17
  @time_range = time_range
14
18
  @analyzer = analyzer
@@ -18,18 +22,16 @@ module PaperTrailDiff
18
22
 
19
23
  #: () -> Hash[Array[String], Analysis?]
20
24
  def call
21
- empty = {} #: Hash[Array[String], Analysis?]
22
- return empty.freeze if @identities.empty?
23
-
24
- records = historical_roots
25
- selected = BatchedRootVersions.new(
26
- records, time_range: @time_range, version_scope: @version_scope
27
- ).call
28
- prepare(records, selected)
25
+ destroys = destroy_versions
26
+ records = historical_roots(destroys)
27
+ windows = TransactionCut.batch_windows(records, @time_range)
28
+ selected = plans(records, destroys, windows)
29
+ prepare(records, selected, windows)
29
30
  analyses = records.to_h do |record|
30
31
  key = Endpoint.identity(record)
31
32
  plan = selected.fetch(key)
32
- [key, plan.empty? ? Analysis.empty : @analyzer.call(record, plan)]
33
+ window = windows.fetch(key, @time_range)
34
+ [key, plan.empty? ? Analysis.empty : @analyzer.call(record, plan, window)]
33
35
  end
34
36
  with_unavailable(analyses)
35
37
  end
@@ -42,19 +44,39 @@ module PaperTrailDiff
42
44
  end
43
45
 
44
46
  # @rbs @model: untyped
47
+ # @rbs @context_required: bool
45
48
  # @rbs @identities: Array[Array[String]]
46
49
  # @rbs @time_range: TimeRange?
47
50
  # @rbs @analyzer: untyped
48
51
  # @rbs @history_preparer: untyped
49
52
  # @rbs @version_scope: untyped
50
53
 
54
+ # A root destroyed before the window had no state inside it to read, so
55
+ # only the others take the version after the window as context.
56
+ #: (Array[untyped], Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Array[String], RootVersionPlan]
57
+ def plans(records, destroys, windows)
58
+ start = @time_range&.begin_time
59
+ early = destroys.select { |version| start && version.created_at < start }
60
+ .map { |version| version.item_id.to_s }
61
+ before, during = records.partition { |record| early.include?(record.id.to_s) }
62
+ plans_for(during, @context_required, windows).merge(plans_for(before, false, windows))
63
+ end
64
+
65
+ #: (Array[untyped], bool, Hash[Array[String], TimeRange]) -> Hash[Array[String], RootVersionPlan]
66
+ def plans_for(records, context_required, windows)
67
+ BatchedRootVersions.new(
68
+ records, time_range: @time_range, version_scope: @version_scope,
69
+ live_endpoints: nil, context_required: context_required, windows: windows
70
+ ).call
71
+ end
72
+
51
73
  # These records supply identity and model metadata only. Every reported
52
74
  # value comes from the batched historical plan; no per-root reify or live
53
75
  # lookup is needed to get into the comparison engine.
54
- #: () -> Array[untyped]
55
- def historical_roots
76
+ #: (Array[untyped]) -> Array[untyped]
77
+ def historical_roots(destroys)
56
78
  loader = PreparedVersionStateLoader.new
57
- destroy_versions.map do |version|
79
+ destroys.map do |version|
58
80
  model = loader.call(version)&.model_class || Endpoint.model_class(version)
59
81
  record = model.new
60
82
  record[model.primary_key] = version.item_id
@@ -64,30 +86,26 @@ module PaperTrailDiff
64
86
 
65
87
  #: () -> Array[untyped]
66
88
  def destroy_versions
67
- destroys = @model.paper_trail.version_class.where(
68
- item_type: @model.base_class.name, item_id: @identities.map(&:last), event: 'destroy'
69
- )
70
- versions = VersionQuery.chronological(destroys)
71
- versions.group_by { |version| version.item_id.to_s }.values.map do |history|
72
- Support.chronological_sort(history).last
73
- end
89
+ destroys = VersionQuery.for_items(@model, @identities.map(&:last)).where(event: 'destroy')
90
+ # Oldest first, so each item keeps its latest destroy.
91
+ VersionQuery.chronological(destroys).index_by(&:item_id).values
74
92
  end
75
93
 
76
- #: (Array[untyped]) -> Hash[Symbol, untyped]
77
- def preparation_range(versions)
78
- { start_at: @time_range&.begin_time,
94
+ #: (Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Symbol, untyped]
95
+ def preparation_range(versions, windows)
96
+ { start_at: TransactionCut.earliest_start(@time_range, windows),
79
97
  end_at: [@time_range&.end_time, versions.map(&:created_at).max].compact.max }
80
98
  end
81
99
 
82
- #: (Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
83
- def prepare(records, selected)
100
+ #: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], TimeRange]) -> void
101
+ def prepare(records, selected, windows)
84
102
  records.group_by(&:class).each_value do |group|
85
103
  versions = group.flat_map do |record|
86
104
  selected.fetch(Endpoint.identity(record)).reconstruction_versions
87
105
  end
88
106
  next if versions.empty?
89
107
 
90
- @history_preparer.call(group, versions, **preparation_range(versions))
108
+ @history_preparer.call(group, versions, **preparation_range(versions, windows))
91
109
  end
92
110
  end
93
111
  end
@@ -0,0 +1,79 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Keeps the deleted roots the relation would have selected, by the state
6
+ # each held when it was destroyed. A relation's conditions read the live
7
+ # table, where a destroyed root has no row, so without this a report on one
8
+ # account's records would include every account's deletions.
9
+ class DeletedRootFilter
10
+ #: (untyped) -> void
11
+ def initialize(relation)
12
+ @relation = relation
13
+ condition = ScopeCondition.for_relation(relation, model)
14
+ unless condition
15
+ raise ConfigurationError,
16
+ 'include_deleted: cannot test deleted records against this relation: its ' \
17
+ "conditions must be plain conditions on #{model.name}'s own columns, as an " \
18
+ "association scope's must; select deleted records some other way"
19
+ end
20
+
21
+ @condition = condition
22
+ @loader = DirectRecordStateLoader.new
23
+ end
24
+
25
+ # A root whose destroy PaperTrail did not record has no state to test
26
+ # and stays, as it has no state to report either. One whose destroy
27
+ # recorded no state is left out.
28
+ #: (Array[Array[String]]) -> Array[Array[String]]
29
+ def call(identities)
30
+ states = destroyed_states(identities.map(&:last))
31
+ identities.select do |identity|
32
+ id = identity.last
33
+ !states.key?(id) || selected?(states.fetch(id))
34
+ end
35
+ end
36
+
37
+ private
38
+
39
+ # @rbs @relation: untyped
40
+ # @rbs @condition: ScopeCondition
41
+ # @rbs @loader: DirectRecordStateLoader
42
+
43
+ # A relation delegates class methods to its model, so every mutation here,
44
+ # which drops `.model`, answers the same.
45
+ # mutant:disable
46
+ #: () -> untyped
47
+ def model
48
+ @relation.model
49
+ end
50
+
51
+ #: (Hash[String, untyped]?) -> bool
52
+ def selected?(attributes)
53
+ return false unless attributes
54
+
55
+ AssociationTraversal.sti_member?(model, attributes) && @condition.matches?(attributes)
56
+ end
57
+
58
+ # The state each root held before its latest destroy.
59
+ #: (Array[String]) -> Hash[String, Hash[String, untyped]?]
60
+ def destroyed_states(ids)
61
+ destroys = VersionQuery.for_items(model, ids).where(event: 'destroy')
62
+ VersionQuery.chronological(destroys).to_h do |version|
63
+ [version.item_id.to_s, @loader.call(version)&.attributes || reified_attributes(version)]
64
+ end
65
+ end
66
+
67
+ # Read directly, with a column `skip:` left out of history as its default,
68
+ # so a report checks its ceiling before reifying anything. A version the
69
+ # direct reader declines, such as one naming a column since removed, is
70
+ # reified. Only the record's own attributes are read, so the association
71
+ # options, which only spare queries, cannot change an answer.
72
+ # mutant:disable
73
+ #: (untyped) -> Hash[String, untyped]?
74
+ def reified_attributes(version)
75
+ version.reify(dup: true, has_many: false, has_one: false, belongs_to: false,
76
+ has_and_belongs_to_many: false)&.attributes
77
+ end
78
+ end
79
+ end
@@ -0,0 +1,61 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Warns about options that do nothing any more and will be removed. In a
6
+ # Rails app, register the deprecator to configure it with the app's own:
7
+ #
8
+ # Rails.application.deprecators[:paper_trail_diff] = PaperTrailDiff.deprecator
9
+ module Deprecation
10
+ CLOSE_ON = 'close_on: is deprecated and has no effect: a window already closes on the ' \
11
+ 'current record when nothing on its requested paths was recorded after it. ' \
12
+ 'Remove the option.'
13
+ ALLOW_EXPENSIVE = 'allow_expensive: is deprecated and has no effect: allow_approximate: true ' \
14
+ 'alone accepts a path read with PT-AT, in batch methods too. Remove the ' \
15
+ 'option.'
16
+ RELOAD_LIVE_ENDPOINTS = 'reload_live_endpoints: is deprecated and will be removed: skipping ' \
17
+ 'the reload saves a query for the records and one per association ' \
18
+ 'level, and reads values that may be stale. Remove the option.'
19
+
20
+ # Required when first used, as the library loads nothing it does not need.
21
+ #: () -> untyped
22
+ def self.deprecator
23
+ @deprecator ||= begin
24
+ require 'active_support/deprecation'
25
+ active_support = Object.const_get(:ActiveSupport) #: untyped
26
+ active_support.const_get(:Deprecation).new('a future release', 'paper_trail_diff')
27
+ end
28
+ end
29
+
30
+ # The one value close_on: took. It named what ends a wall-clock window,
31
+ # so it was meaningless without one, and until it is removed it is still
32
+ # checked as it was.
33
+ CLOSE_ON_CURRENT = :current
34
+
35
+ #: (Symbol?, untyped) -> void
36
+ def self.close_on!(close_on, within)
37
+ return if close_on.nil?
38
+ unless close_on == CLOSE_ON_CURRENT
39
+ raise ConfigurationError, "close_on: must be #{CLOSE_ON_CURRENT.inspect} or nil"
40
+ end
41
+ raise ConfigurationError, 'close_on: requires `within`' if within.nil?
42
+
43
+ deprecator.warn(CLOSE_ON)
44
+ end
45
+
46
+ #: (untyped) -> void
47
+ def self.allow_expensive!(allow_expensive)
48
+ deprecator.warn(ALLOW_EXPENSIVE) unless allow_expensive.nil?
49
+ end
50
+
51
+ # The value to use: the option still works until it is removed, and nil
52
+ # stands for its old default.
53
+ #: (untyped) -> untyped
54
+ def self.reload_live_endpoints!(reload)
55
+ return true if reload.nil?
56
+
57
+ deprecator.warn(RELOAD_LIVE_ENDPOINTS)
58
+ reload
59
+ end
60
+ end
61
+ end
@@ -64,87 +64,144 @@ module PaperTrailDiff
64
64
  end
65
65
 
66
66
  # Performs read-only checks for known PaperTrail/PT-AT reconstruction hazards.
67
+ #
68
+ # The endpoints are a comparison's: two versions, or a version and the
69
+ # current record, in either order. Two current records read no history, so
70
+ # nothing is checked.
67
71
  class HistoryDiagnostics
68
- #: (untyped, untyped, associations: Array[String | Symbol]) -> void
69
- def initialize(from_version, to_version, associations:)
70
- @from_version = from_version
71
- @to_version = to_version
72
+ STOPPING_CODES = %i[
73
+ unknown_association unsupported_association association_tracking_unavailable
74
+ ].freeze
75
+
76
+ #: (untyped, untyped, associations: association_option, ?allow_approximate: bool) -> void
77
+ def initialize(from, to, associations:, allow_approximate: false)
78
+ @versions = validated_versions(from, to)
72
79
  @tree = AssociationTree.build(associations)
80
+ @traversal = AssociationTraversal.new(@tree)
81
+ @preparer = TraversalPreparer.new(tree: @tree, traversal: @traversal,
82
+ allow_approximate: allow_approximate)
83
+ @allow_approximate = allow_approximate
73
84
  @issues = [] #: Array[DiagnosticIssue]
74
85
  end
75
86
 
76
87
  #: () -> DiagnosticReport
77
88
  def call
78
- model_class = validated_model_class
79
- # Runs whether or not associations are selected: unorderable versions
80
- # corrupt a scalar timeline just as surely, and a report that inspected
81
- # nothing has no business answering `ok?`.
82
- inspect_version_sequence
83
- return DiagnosticReport.new(issues: @issues) if @tree.empty?
84
-
85
- unless association_tracking_available?
86
- add_error(:association_tracking_unavailable, tracking_unavailable_message)
87
- return DiagnosticReport.new(issues: @issues)
89
+ unless @versions.empty?
90
+ model_class = Endpoint.model_class(@versions.fetch(0))
91
+ # Runs whether or not associations are selected: unorderable versions
92
+ # corrupt a scalar timeline just as surely, and a report that inspected
93
+ # nothing has no business answering `ok?`.
94
+ inspect_version_sequence(model_class)
95
+ inspect_associations(model_class) unless @tree.empty?
88
96
  end
89
-
90
- traversal = AssociationTraversal.new(@tree)
91
- selected = traversal.selected_reflections(model_class)
92
- inspect_targets(selected)
93
- inspect_checkpoint_timestamp(model_class)
94
- inspect_habtm(selected)
95
97
  DiagnosticReport.new(issues: @issues)
96
98
  end
97
99
 
98
100
  private
99
101
 
100
- # @rbs @from_version: untyped
101
- # @rbs @to_version: untyped
102
+ # Each refusal a comparison would raise is an error, so `ok?` is false
103
+ # exactly when one would. The checks after them read reflections that must
104
+ # resolve and PT-AT records that must be there.
105
+ #: (untyped) -> void
106
+ def inspect_associations(model_class)
107
+ refusals = @preparer.refusals(model_class, historical: true)
108
+ refusals.each { |refusal| add_error(refusal.code, refusal.message, refusal.path) }
109
+ return if refusals.any? { |refusal| STOPPING_CODES.include?(refusal.code) }
110
+
111
+ selected = @traversal.selected_reflections(model_class)
112
+ inspect_polymorphic_targets(selected)
113
+ inspect_approximate_paths(model_class) if @allow_approximate
114
+ inspect_checkpoint_timestamp(model_class)
115
+ inspect_habtm(model_class, selected)
116
+ end
117
+
118
+ # @rbs @versions: Array[untyped]
102
119
  # @rbs @tree: AssociationTree
120
+ # @rbs @traversal: AssociationTraversal
121
+ # @rbs @preparer: TraversalPreparer
122
+ # @rbs @allow_approximate: bool
103
123
  # @rbs @issues: Array[DiagnosticIssue]
104
124
 
105
- #: () -> untyped
106
- def validated_model_class
107
- unless version_identity(@from_version) == version_identity(@to_version)
108
- raise VersionMismatchError, 'versions must belong to the same PaperTrail item'
125
+ # The endpoints that are versions, in the order given.
126
+ #: (untyped, untyped) -> Array[untyped]
127
+ def validated_versions(from, to)
128
+ Endpoint.validate!(from)
129
+ Endpoint.validate!(to)
130
+ unless Endpoint.identity(from) == Endpoint.identity(to)
131
+ raise VersionMismatchError, 'endpoints must belong to the same PaperTrail item'
109
132
  end
110
133
 
111
- Object.const_get(version_type(@from_version))
112
- rescue NoMethodError => e
113
- raise VersionMismatchError, 'expected PaperTrail version endpoints', cause: e
134
+ [from, to].select { |endpoint| Endpoint.version?(endpoint) }
114
135
  end
115
136
 
116
137
  #: (Array[Array[untyped]]) -> void
117
- def inspect_targets(selected)
138
+ def inspect_polymorphic_targets(selected)
118
139
  selected.each do |path, reflection|
119
- if reflection.polymorphic?
120
- add_warning(:polymorphic_target_unverified, 'polymorphic target cannot be verified', path)
121
- next
122
- end
140
+ next unless reflection.polymorphic?
123
141
 
124
- inspect_versioned_model(reflection.klass, path)
125
- inspect_through_model(reflection, path) if reflection.options[:through]
142
+ add_warning(:polymorphic_target_unverified, 'polymorphic target cannot be verified', path)
126
143
  end
127
144
  end
128
145
 
129
- #: (Array[Array[untyped]]) -> void
130
- def inspect_habtm(selected)
131
- paths = selected.filter_map do |path, reflection|
132
- path if reflection.macro == :has_and_belongs_to_many
146
+ # Accepted, but read the way `allow_approximate:` describes.
147
+ #: (untyped) -> void
148
+ def inspect_approximate_paths(model_class)
149
+ ApproximatePaths.call(@traversal, model_class).each do |path, reason|
150
+ add_warning(:approximate_association,
151
+ "association #{path} is read approximately with PT-AT (#{reason}): a " \
152
+ 'record that entered or left it since is reported wrongly', path)
133
153
  end
134
- return if paths.empty?
154
+ end
135
155
 
136
- inspect_transaction_metadata(paths)
156
+ #: (untyped, Array[Array[untyped]]) -> void
157
+ def inspect_habtm(model_class, selected)
158
+ habtm = selected.select { |_, reflection| reflection.macro == :has_and_belongs_to_many }
159
+ return if habtm.empty?
160
+
161
+ inspect_transaction_metadata(habtm.map(&:first))
162
+ inspect_shared_transactions(model_class, habtm)
163
+ end
164
+
165
+ # PT-AT does not record which owner a HABTM member belongs to, so a
166
+ # transaction that more than one owner recorded members in cannot be read.
167
+ #: (untyped, Array[Array[untyped]]) -> void
168
+ def inspect_shared_transactions(model_class, habtm)
169
+ versions = @versions.select { |version| VersionBoundary.transaction_id(version) }
170
+ habtm.each do |path, reflection|
171
+ owners = HabtmTransactionOwners.new(model_class, reflection)
172
+ versions.each do |version|
173
+ next unless owners.ambiguous?(version.transaction_id)
174
+
175
+ add_error(:habtm_transaction_shared,
176
+ 'HABTM endpoint shares its transaction with another owner of the association',
177
+ path, version.id)
178
+ end
179
+ end
137
180
  end
138
181
 
139
- #: () -> void
140
- def inspect_version_sequence
182
+ # With the current record as one endpoint there is one version, and the
183
+ # sequence runs on from it.
184
+ #: (untyped) -> void
185
+ def inspect_version_sequence(model_class)
186
+ first, last = @versions
141
187
  @issues.concat(
142
- VersionSequenceDiagnostics.new(
143
- @from_version, @to_version, associations_selected: !@tree.empty?
144
- ).call
188
+ VersionSequenceDiagnostics.new(first, last,
189
+ fallback_selected: fallback_selected?(model_class)).call
145
190
  )
146
191
  end
147
192
 
193
+ # Only a path PT-AT reads can lose a change between tied versions, and a
194
+ # traversal that does not resolve reads nothing at all.
195
+ #: (untyped) -> bool
196
+ def fallback_selected?(model_class)
197
+ return false if @tree.empty?
198
+
199
+ refusals = @preparer.refusals(model_class, historical: true)
200
+ return false if refusals.any? { |refusal| STOPPING_CODES.include?(refusal.code) }
201
+
202
+ FallbackPaths.any?(@traversal, model_class, approximate: @allow_approximate)
203
+ end
204
+
148
205
  #: (untyped) -> void
149
206
  def inspect_checkpoint_timestamp(model_class)
150
207
  return if synchronized_timestamp_disabled?(model_class)
@@ -155,7 +212,7 @@ module PaperTrailDiff
155
212
 
156
213
  #: (Array[String]) -> void
157
214
  def inspect_transaction_metadata(paths)
158
- [@from_version, @to_version].each do |version|
215
+ @versions.each do |version|
159
216
  if !version.respond_to?(:transaction_id)
160
217
  add_error(:transaction_id_column_missing, 'version has no transaction_id column')
161
218
  elsif version.transaction_id.nil?
@@ -171,36 +228,6 @@ module PaperTrailDiff
171
228
  end
172
229
  end
173
230
 
174
- #: (untyped, String) -> void
175
- def inspect_versioned_model(model_class, path)
176
- return if model_versioned?(model_class)
177
-
178
- # An error rather than a warning: `ok?` must not stay true for a
179
- # comparison that cannot work, and this one raises at runtime.
180
- add_error(
181
- :unversioned_association_target,
182
- "#{model_class.name} does not appear to have PaperTrail enabled",
183
- path
184
- )
185
- end
186
-
187
- #: (untyped, String) -> void
188
- def inspect_through_model(reflection, path)
189
- model_class = reflection.through_reflection.klass
190
- return if model_versioned?(model_class)
191
-
192
- add_warning(
193
- :unversioned_through_model,
194
- "#{model_class.name} does not appear to have PaperTrail enabled",
195
- path
196
- )
197
- end
198
-
199
- #: (untyped) -> bool
200
- def model_versioned?(model_class)
201
- Support.versioned?(model_class)
202
- end
203
-
204
231
  #: (untyped) -> bool
205
232
  def synchronized_timestamp_disabled?(model_class)
206
233
  options = model_class.paper_trail_options
@@ -209,30 +236,6 @@ module PaperTrailDiff
209
236
  false
210
237
  end
211
238
 
212
- #: () -> bool
213
- def association_tracking_available?
214
- paper_trail = Object.const_get(:PaperTrail) #: untyped
215
- config = paper_trail.config #: untyped
216
- !!(defined?(::PaperTrailAssociationTracking) &&
217
- config.respond_to?(:track_associations?) && config.track_associations?)
218
- end
219
-
220
- #: (untyped) -> Array[String]
221
- def version_identity(version)
222
- [version.item_type.to_s, version.item_id.to_s]
223
- end
224
-
225
- #: (untyped) -> String
226
- def version_type(version)
227
- subtype = version.item_subtype if version.respond_to?(:item_subtype)
228
- subtype.to_s.empty? ? version.item_type.to_s : subtype.to_s
229
- end
230
-
231
- #: () -> String
232
- def tracking_unavailable_message
233
- 'association tracking must be loaded and enabled to diagnose associations'
234
- end
235
-
236
239
  #: (Symbol, String, ?String?, ?untyped) -> void
237
240
  def add_error(code, message, path = nil, version_id = nil)
238
241
  add_issue(:error, code, message, path, version_id)
@@ -45,13 +45,22 @@ module PaperTrailDiff
45
45
 
46
46
  #: (untyped) -> bool
47
47
  def plain_model?(model)
48
- !model.primary_key.is_a?(Array) && !model.default_scopes? &&
48
+ !model.primary_key.is_a?(Array) && !scope_assigns_attributes?(model) &&
49
49
  model._initialize_callbacks.empty? &&
50
50
  %i[initialize attributes []= write_attribute id].all? do |name|
51
51
  framework_class?(model.instance_method(name).owner)
52
52
  end
53
53
  end
54
54
 
55
+ # A default scope's equality conditions are assigned to every new record,
56
+ # through the model's writers, before a reified version's attributes are.
57
+ # A subclass's own type is assigned with or without one.
58
+ #: (untyped) -> bool
59
+ def scope_assigns_attributes?(model)
60
+ model.default_scopes? &&
61
+ model.default_scoped.scope_for_create != model.unscoped.scope_for_create
62
+ end
63
+
55
64
  #: (untyped) -> bool
56
65
  def plain_attributes?(model)
57
66
  return false if encrypted?(model)
@@ -47,6 +47,29 @@ module PaperTrailDiff
47
47
  validate_record!(endpoint)
48
48
  end
49
49
 
50
+ # The record a method reads the history of: a record, saved or destroyed,
51
+ # of a model PaperTrail versions.
52
+ #: (untyped) -> void
53
+ def validate_root!(record)
54
+ unless record?(record)
55
+ raise InvalidEndpointError, "expected a record, got #{described(record)}"
56
+ end
57
+ return if Support.versioned?(record.class)
58
+
59
+ raise InvalidEndpointError,
60
+ "#{record.class.name} is not versioned, so it has no history: add has_paper_trail to it"
61
+ end
62
+
63
+ # A relation is named rather than inspected, which would load it.
64
+ #: (untyped) -> String
65
+ def described(value)
66
+ return 'nil' if value.nil?
67
+ return "the class #{value.name}" if value.is_a?(Module)
68
+
69
+ value.class.name.to_s
70
+ end
71
+ private_class_method :described
72
+
50
73
  #: (untyped) -> bool
51
74
  def version?(endpoint)
52
75
  endpoint.respond_to?(:reify) &&
@@ -82,11 +105,11 @@ module PaperTrailDiff
82
105
  raise InvalidEndpointError, "cannot resolve endpoint model: #{model_type}", cause: e
83
106
  end
84
107
 
85
- # The record's own PaperTrail versions, under whatever name the model gave
86
- # the association.
108
+ # Every PaperTrail version of the record, whatever scope its versions
109
+ # association has.
87
110
  #: (untyped) -> untyped
88
111
  def versions(record)
89
- record.public_send(record.class.versions_association_name)
112
+ VersionQuery.for_items(record.class, record.id)
90
113
  rescue NoMethodError => e
91
114
  message = 'record does not expose a PaperTrail version history'
92
115
  raise InvalidTimelineRangeError, message, cause: e
@@ -42,7 +42,9 @@ module PaperTrailDiff
42
42
  # Historical candidate loading exceeded its explicitly bounded work budget.
43
43
  class FilterLimitExceededError < Error; end
44
44
 
45
- # A batch selected a known expensive association without explicitly opting in.
45
+ # No longer raised: `allow_approximate: true` alone accepts the paths it
46
+ # refused. Kept until `allow_expensive:` is removed, so code that rescues it
47
+ # still loads.
46
48
  class UnsupportedBatchPathError < ConfigurationError; end
47
49
 
48
50
  # Raised when a requested ActiveRecord association does not exist.
@@ -58,7 +60,8 @@ module PaperTrailDiff
58
60
  # Raised when association comparison is requested without an available PT-AT setup.
59
61
  class AssociationTrackingUnavailableError < Error; end
60
62
 
61
- # Raised when recorded PT-AT metadata cannot reliably reconstruct a selected association.
63
+ # Raised when recorded PT-AT metadata cannot reliably reconstruct a selected association,
64
+ # or a polymorphic type names no class.
62
65
  class IncompleteAssociationHistoryError < Error; end
63
66
 
64
67
  # Raised when current-ended activity cannot be reconstructed for a selected association.
@@ -0,0 +1,38 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Whether a request may read a path with PT-AT's reifier rather than from
6
+ # loaded history. PT-AT places association changes by timestamp alone, so
7
+ # only such a path can miss a change between two versions that share one;
8
+ # loaded history orders those versions by id.
9
+ module FallbackPaths
10
+ # A path history reads only approximately counts when it is allowed: a
11
+ # request that does not allow it is refused before anything is read.
12
+ #: (AssociationTraversal, untyped, approximate: bool) -> bool
13
+ def self.any?(traversal, model, approximate:)
14
+ return true if approximate && !ApproximatePaths.call(traversal, model).empty?
15
+
16
+ traversal.selected_reflections(model).any? { |_path, reflection| per_record?(reflection) }
17
+ end
18
+
19
+ # Loaded history cannot index a composite foreign key, and a polymorphic
20
+ # belongs_to's target, with its default scope, is known only per record.
21
+ #: (untyped) -> bool
22
+ def self.per_record?(reflection)
23
+ composite_key?(reflection) || (reflection.belongs_to? && reflection.polymorphic?)
24
+ end
25
+ private_class_method :per_record?
26
+
27
+ #: (untyped) -> bool
28
+ def self.composite_key?(reflection)
29
+ return true if reflection.foreign_key.is_a?(Array)
30
+ return false unless reflection.through_reflection?
31
+
32
+ [reflection.through_reflection, reflection.source_reflection].any? do |part|
33
+ composite_key?(part)
34
+ end
35
+ end
36
+ private_class_method :composite_key?
37
+ end
38
+ end