paper_trail_diff 0.13.0 → 0.14.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 (121) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +318 -0
  3. data/QUICKSTART.md +9 -6
  4. data/README.md +84 -9
  5. data/docs/architecture.md +32 -9
  6. data/docs/performance.md +106 -13
  7. data/docs/reference.md +242 -29
  8. data/docs/testing.md +55 -9
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +19 -9
  10. data/lib/paper_trail_diff/activity_collection_event_applier.rb +11 -1
  11. data/lib/paper_trail_diff/activity_collection_record_updater.rb +16 -2
  12. data/lib/paper_trail_diff/activity_event_record_resolver.rb +20 -1
  13. data/lib/paper_trail_diff/activity_event_route_finder.rb +2 -1
  14. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +1 -1
  15. data/lib/paper_trail_diff/activity_range.rb +14 -2
  16. data/lib/paper_trail_diff/activity_relationship.rb +12 -0
  17. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +5 -2
  18. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +131 -0
  19. data/lib/paper_trail_diff/activity_timeline_builder.rb +30 -24
  20. data/lib/paper_trail_diff/activity_version_collector.rb +31 -20
  21. data/lib/paper_trail_diff/association_activity_edge.rb +236 -0
  22. data/lib/paper_trail_diff/association_activity_selection.rb +197 -0
  23. data/lib/paper_trail_diff/association_discovery.rb +8 -13
  24. data/lib/paper_trail_diff/association_traversal.rb +169 -45
  25. data/lib/paper_trail_diff/batch_safety.rb +23 -15
  26. data/lib/paper_trail_diff/batched_root_versions.rb +21 -39
  27. data/lib/paper_trail_diff/collection_comparator.rb +18 -20
  28. data/lib/paper_trail_diff/collection_identity_index.rb +8 -12
  29. data/lib/paper_trail_diff/comparison_batch.rb +37 -10
  30. data/lib/paper_trail_diff/deleted_analysis_batch.rb +36 -17
  31. data/lib/paper_trail_diff/diagnostics.rb +26 -8
  32. data/lib/paper_trail_diff/direct_record_state_loader.rb +10 -1
  33. data/lib/paper_trail_diff/errors.rb +2 -1
  34. data/lib/paper_trail_diff/habtm_transaction_owners.rb +68 -0
  35. data/lib/paper_trail_diff/historical_association_reifier.rb +32 -2
  36. data/lib/paper_trail_diff/historical_filter.rb +12 -17
  37. data/lib/paper_trail_diff/historical_snapshot_store.rb +6 -9
  38. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +35 -2
  39. data/lib/paper_trail_diff/live_graph_collector.rb +1 -1
  40. data/lib/paper_trail_diff/paper_trail_adapter.rb +22 -6
  41. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +1 -1
  42. data/lib/paper_trail_diff/prepared_activity_index.rb +110 -36
  43. data/lib/paper_trail_diff/prepared_edge_loader.rb +29 -45
  44. data/lib/paper_trail_diff/prepared_history.rb +63 -54
  45. data/lib/paper_trail_diff/prepared_history_loader.rb +33 -43
  46. data/lib/paper_trail_diff/prepared_record_index.rb +26 -0
  47. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +1 -1
  48. data/lib/paper_trail_diff/prepared_state_association_reader.rb +119 -29
  49. data/lib/paper_trail_diff/recorded_changes.rb +83 -0
  50. data/lib/paper_trail_diff/recorded_class.rb +53 -0
  51. data/lib/paper_trail_diff/root_version_plan.rb +10 -1
  52. data/lib/paper_trail_diff/scope_condition.rb +331 -0
  53. data/lib/paper_trail_diff/scope_ranking.rb +196 -0
  54. data/lib/paper_trail_diff/scoped_analysis_builder.rb +4 -3
  55. data/lib/paper_trail_diff/scoped_root_selection.rb +93 -43
  56. data/lib/paper_trail_diff/snapshot.rb +5 -1
  57. data/lib/paper_trail_diff/snapshot_normalizer.rb +50 -47
  58. data/lib/paper_trail_diff/support.rb +9 -4
  59. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -1
  60. data/lib/paper_trail_diff/time_range.rb +9 -13
  61. data/lib/paper_trail_diff/time_version_range.rb +6 -6
  62. data/lib/paper_trail_diff/timeline_range.rb +5 -4
  63. data/lib/paper_trail_diff/version.rb +1 -1
  64. data/lib/paper_trail_diff/version_association_candidate_scope.rb +13 -3
  65. data/lib/paper_trail_diff/version_query.rb +9 -1
  66. data/lib/paper_trail_diff/version_range.rb +8 -15
  67. data/lib/paper_trail_diff/version_scope_filter.rb +11 -3
  68. data/lib/paper_trail_diff.rb +31 -2
  69. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +10 -2
  70. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +5 -0
  71. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +5 -0
  72. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +7 -0
  73. data/sig/generated/paper_trail_diff/activity_range.rbs +6 -2
  74. data/sig/generated/paper_trail_diff/activity_relationship.rbs +3 -0
  75. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +2 -0
  76. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +79 -0
  77. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +11 -5
  78. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +10 -4
  79. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +148 -0
  80. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +112 -0
  81. data/sig/generated/paper_trail_diff/association_discovery.rbs +3 -5
  82. data/sig/generated/paper_trail_diff/association_traversal.rbs +84 -9
  83. data/sig/generated/paper_trail_diff/batch_safety.rbs +10 -4
  84. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +2 -8
  85. data/sig/generated/paper_trail_diff/collection_comparator.rbs +6 -3
  86. data/sig/generated/paper_trail_diff/collection_identity_index.rbs +3 -3
  87. data/sig/generated/paper_trail_diff/comparison_batch.rbs +22 -4
  88. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +16 -4
  89. data/sig/generated/paper_trail_diff/diagnostics.rbs +7 -2
  90. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +6 -0
  91. data/sig/generated/paper_trail_diff/errors.rbs +2 -1
  92. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +40 -0
  93. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +13 -0
  94. data/sig/generated/paper_trail_diff/historical_filter.rbs +6 -6
  95. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +3 -2
  96. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +17 -0
  97. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +5 -0
  98. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +52 -10
  99. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -12
  100. data/sig/generated/paper_trail_diff/prepared_history.rbs +33 -22
  101. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +15 -13
  102. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +15 -0
  103. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +56 -11
  104. data/sig/generated/paper_trail_diff/recorded_changes.rbs +47 -0
  105. data/sig/generated/paper_trail_diff/recorded_class.rbs +22 -0
  106. data/sig/generated/paper_trail_diff/root_version_plan.rbs +7 -0
  107. data/sig/generated/paper_trail_diff/scope_condition.rbs +185 -0
  108. data/sig/generated/paper_trail_diff/scope_ranking.rbs +117 -0
  109. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +2 -2
  110. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +41 -7
  111. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +25 -9
  112. data/sig/generated/paper_trail_diff/support.rbs +5 -2
  113. data/sig/generated/paper_trail_diff/time_range.rbs +4 -0
  114. data/sig/generated/paper_trail_diff/time_version_range.rbs +4 -4
  115. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -1
  116. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +7 -0
  117. data/sig/generated/paper_trail_diff/version_query.rbs +7 -1
  118. data/sig/generated/paper_trail_diff/version_range.rbs +4 -2
  119. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +4 -0
  120. data/sig/generated/paper_trail_diff.rbs +21 -2
  121. metadata +20 -4
@@ -4,16 +4,17 @@
4
4
  module PaperTrailDiff
5
5
  # Expands the explicit association tree into a request-scoped PreparedHistory.
6
6
  class PreparedHistoryLoader
7
- #: (untyped, root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, ?root_ids: Array[untyped], ?start_at: untyped, ?end_at: untyped, ?live_records: Array[untyped]) -> void
7
+ # Without `end_at`, the activity range closes on the last root version.
8
+ #: (untyped, root_ids: Array[untyped], root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, start_at: untyped, end_at: untyped, live_records: Array[untyped]) -> void
8
9
  def initialize( # rubocop:disable Metrics/ParameterLists
9
10
  record,
11
+ root_ids:,
10
12
  root_versions:,
11
13
  tree:,
12
14
  traversal:,
13
- root_ids: [record.id],
14
- start_at: root_versions.first.created_at,
15
- end_at: nil,
16
- live_records: []
15
+ start_at:,
16
+ end_at:,
17
+ live_records:
17
18
  )
18
19
  @record = record
19
20
  @root_ids = root_ids
@@ -21,12 +22,12 @@ module PaperTrailDiff
21
22
  @tree = tree
22
23
  @traversal = traversal
23
24
  @records = PreparedRecordIndex.new(start_at, end_at: end_at, live_records: live_records)
24
- activity = PreparedActivityIndex.new(
25
+ @activity = PreparedActivityIndex.new(
25
26
  @records, root_versions, start_at: start_at, end_at: end_at || root_versions.last.created_at
26
27
  )
27
- @history = PreparedHistory.new(@records, activity_index: activity)
28
+ @history = PreparedHistory.new(@records, activity_index: @activity)
28
29
  @edges = PreparedEdgeLoader.new(@records, root_versions, start_at: start_at)
29
- @prepared = {} #: Hash[Array[String], Array[String]]
30
+ @prepared = {} #: Hash[untyped, Array[String]]
30
31
  end
31
32
 
32
33
  #: () -> PreparedHistory
@@ -44,20 +45,18 @@ module PaperTrailDiff
44
45
  # @rbs @tree: AssociationTree
45
46
  # @rbs @traversal: AssociationTraversal
46
47
  # @rbs @records: PreparedRecordIndex
48
+ # @rbs @activity: PreparedActivityIndex
47
49
  # @rbs @history: PreparedHistory
48
50
  # @rbs @edges: PreparedEdgeLoader
49
- # @rbs @prepared: Hash[Array[String], Array[String]]
51
+ # @rbs @prepared: Hash[untyped, Array[String]]
50
52
 
51
53
  #: (untyped, Array[untyped], AssociationTree, path: String) -> void
52
54
  def load_node(model_class, ids, tree, path:)
53
- @history.activity_index&.register(model_class, ids)
55
+ @activity.register(model_class, ids)
54
56
  @traversal.reflections_for(model_class, tree, path: path).each do |reflection|
55
- subtree = tree.child(reflection.name)
56
- next unless subtree
57
-
57
+ subtree = tree.child(reflection.name) #: AssociationTree
58
58
  groups = prepare_reflection(model_class, ids, reflection)
59
- load_groups(groups)
60
- child_path = Support.association_path(path, reflection.name.to_s)
59
+ child_path = Support.association_path(path, reflection.name)
61
60
  groups.each_value do |group|
62
61
  load_node(group.fetch(:model), group.fetch(:ids), subtree, path: child_path)
63
62
  end
@@ -66,70 +65,66 @@ module PaperTrailDiff
66
65
 
67
66
  #: (untyped, Array[untyped], untyped) -> Hash[String, Hash[Symbol, untyped]]
68
67
  def prepare_reflection(owner_class, owner_ids, reflection)
69
- return prepare_through(owner_class, owner_ids, reflection) if reflection.options[:through]
68
+ return prepare_through(owner_class, owner_ids, reflection) if reflection.through_reflection?
70
69
 
71
70
  prepare_edge(owner_class, owner_ids, reflection)
72
71
  end
73
72
 
73
+ # Either part can itself be a through, which has no key of its own to
74
+ # read, so each part is prepared as what it is. Like an edge, it returns
75
+ # every group it holds, not only those of these owners.
74
76
  #: (untyped, Array[untyped], untyped) -> Hash[String, Hash[Symbol, untyped]]
75
77
  def prepare_through(owner_class, owner_ids, reflection)
76
- through_groups = prepare_edge(owner_class, owner_ids, reflection.through_reflection)
78
+ through_groups = prepare_reflection(owner_class, owner_ids, reflection.through_reflection)
77
79
  targets = {} #: Hash[String, Hash[Symbol, untyped]]
78
80
  through_groups.each_value do |group|
79
- load_groups({ group.fetch(:model).name.to_s => group })
80
- source = prepare_edge(group.fetch(:model), group.fetch(:ids), reflection.source_reflection)
81
+ source = prepare_reflection(group.fetch(:model), group.fetch(:ids),
82
+ reflection.source_reflection)
81
83
  targets = merge_groups(targets, source)
82
84
  end
83
85
  @history.merge_edge(owner_class, reflection, targets)
84
- @history.mark_unsupported(owner_class, reflection) if deferred_macro?(reflection)
85
- targets
86
86
  end
87
87
 
88
88
  #: (untyped, Array[untyped], untyped) -> Hash[String, Hash[Symbol, untyped]]
89
89
  def prepare_edge(owner_class, owner_ids, reflection)
90
- missing = unprepared_ids(owner_class, owner_ids, reflection)
90
+ missing = unprepared_ids(owner_ids, reflection)
91
91
  return @history.edge(owner_class, reflection) if missing.empty?
92
92
 
93
- load_records(owner_class, missing) if reflection.macro == :belongs_to
94
93
  groups, memberships = @edges.call(owner_class, missing, reflection)
95
94
  @history.merge_edge(owner_class, reflection, groups)
96
95
  @history.register_habtm(owner_class, reflection, memberships) if memberships
97
- mark_prepared(owner_class, missing, reflection)
96
+ mark_prepared(missing, reflection)
98
97
  mark_unsupported(owner_class, reflection, groups)
99
98
  load_groups(groups)
100
99
  @history.edge(owner_class, reflection)
101
100
  end
102
101
 
103
- #: (untyped, Array[untyped], untyped) -> Array[untyped]
104
- def unprepared_ids(owner_class, ids, reflection)
105
- prepared = @prepared.fetch(edge_key(owner_class, reflection), [])
102
+ # A reflection belongs to the class that declares it, so it alone names
103
+ # the edge; a subclass that inherits it reads the same records.
104
+ #: (Array[untyped], untyped) -> Array[untyped]
105
+ def unprepared_ids(ids, reflection)
106
+ prepared = @prepared.fetch(reflection, [])
106
107
  ids.reject { |id| prepared.include?(id.to_s) }
107
108
  end
108
109
 
109
- #: (untyped, Array[untyped], untyped) -> void
110
- def mark_prepared(owner_class, ids, reflection)
111
- key = edge_key(owner_class, reflection)
112
- @prepared[key] = (@prepared.fetch(key, []) | ids.map(&:to_s))
110
+ #: (Array[untyped], untyped) -> void
111
+ def mark_prepared(ids, reflection)
112
+ @prepared[reflection] = (@prepared.fetch(reflection, []) | ids.map(&:to_s))
113
113
  end
114
114
 
115
115
  #: (untyped, untyped, Hash[String, Hash[Symbol, untyped]]) -> void
116
116
  def mark_unsupported(owner_class, reflection, groups)
117
- unsupported = deferred_macro?(reflection) || reflection.foreign_key.is_a?(Array) ||
117
+ unsupported = reflection.foreign_key.is_a?(Array) ||
118
118
  groups.values.any? { |group| !versioned?(group.fetch(:model)) }
119
119
  @history.mark_unsupported(owner_class, reflection) if unsupported
120
120
  end
121
121
 
122
- #: (untyped) -> bool
123
- def deferred_macro?(reflection)
124
- reflection.options[:through] && !reflection.source_reflection.belongs_to?
125
- end
126
-
127
122
  #: (Hash[String, Hash[Symbol, untyped]]) -> void
128
123
  def load_groups(groups)
129
124
  groups.each_value do |group|
130
125
  model = group.fetch(:model)
131
126
  ids = group.fetch(:ids)
132
- @history.activity_index&.register(model, ids)
127
+ @activity.register(model, ids)
133
128
  load_records(model, ids)
134
129
  end
135
130
  end
@@ -144,11 +139,6 @@ module PaperTrailDiff
144
139
  Support.versioned?(model_class)
145
140
  end
146
141
 
147
- #: (untyped, untyped) -> Array[String]
148
- def edge_key(owner_class, reflection)
149
- [owner_class.base_class.name.to_s, reflection.name.to_s]
150
- end
151
-
152
142
  #: (Hash[String, Hash[Symbol, untyped]], Hash[String, Hash[Symbol, untyped]]) -> Hash[String, Hash[Symbol, untyped]]
153
143
  def merge_groups(left, right)
154
144
  Support.merge_record_groups(left, right)
@@ -163,6 +163,22 @@ module PaperTrailDiff
163
163
  live ? [*recorded, live] : recorded
164
164
  end
165
165
 
166
+ # The classes the record had at any point, or either side of one version.
167
+ #: (?untyped) -> Array[untyped]
168
+ def model_classes(version = nil)
169
+ return states.map(&:model_class) unless version
170
+
171
+ states_around(version).map(&:model_class)
172
+ end
173
+
174
+ # The states either side of one version; a create has none before it and a
175
+ # destroy none after.
176
+ #: (untyped) -> Array[PreparedRecordState]
177
+ def states_around(version)
178
+ index = @version_positions.fetch(version.id.to_s)
179
+ [state_for(version), state_after(index)].compact
180
+ end
181
+
166
182
  #: (untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
167
183
  def transition(version)
168
184
  index = @version_positions[version.id.to_s]
@@ -337,6 +353,16 @@ module PaperTrailDiff
337
353
  @series.fetch(identity(model_class, id)).versions
338
354
  end
339
355
 
356
+ #: (untyped, untyped, ?untyped) -> Array[untyped]
357
+ def model_classes(model_class, id, version = nil)
358
+ @series.fetch(identity(model_class, id)).model_classes(version)
359
+ end
360
+
361
+ #: (untyped, untyped, untyped) -> Array[PreparedRecordState]
362
+ def states_around(model_class, id, version)
363
+ @series.fetch(identity(model_class, id)).states_around(version)
364
+ end
365
+
340
366
  #: (untyped, untyped) -> bool
341
367
  def loaded?(model_class, id)
342
368
  @series.key?(identity(model_class, id))
@@ -49,7 +49,7 @@ module PaperTrailDiff
49
49
  subtree = tree.child(reflection.name)
50
50
  return [false, nil] unless subtree
51
51
 
52
- child_path = Support.association_path(path, reflection.name.to_s)
52
+ child_path = Support.association_path(path, reflection.name)
53
53
  records = [] #: Array[RecordSnapshot]
54
54
  states.each do |state|
55
55
  supported, snapshot = build(state, boundary, subtree, normalizer, history,
@@ -2,71 +2,161 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- # Reads plain direct edges without creating AR records for their members.
5
+ # Reads plain edges without creating AR records for their members: direct
6
+ # edges, polymorphic `belongs_to`, and `has_many :through` built from them.
6
7
  class PreparedStateAssociationReader
7
- #: (PreparedRecordIndex, untyped) -> void
8
- def initialize(records, edges)
8
+ #: (PreparedRecordIndex, untyped, ScopeCondition::Cache) -> void
9
+ def initialize(records, edges, conditions)
9
10
  @records = records
10
11
  @edges = edges
12
+ @conditions = conditions
11
13
  end
12
14
 
13
- #: (PreparedRecordState, untyped, untyped) -> [bool, Array[PreparedRecordState]]
14
- def call(owner, reflection, boundary)
15
- return [false, []] unless supported?(reflection)
15
+ # Unranked, as a part of a has_many through is read, it returns every row
16
+ # the part's conditions admit, a record reached twice appearing twice.
17
+ #: (PreparedRecordState, untyped, untyped, ?ranked: bool) -> [bool, Array[PreparedRecordState]]
18
+ def call(owner, reflection, boundary, ranked: true)
19
+ return [false, []] unless supported?(reflection, ranked)
20
+ return through(owner, reflection, boundary, ranked) if reflection.options[:through]
21
+ return target(owner, reflection, boundary, ranked) if reflection.belongs_to?
16
22
 
17
- if reflection.belongs_to?
18
- id = owner.attributes[reflection.foreign_key.to_s]
19
- return [true, []] if id.nil?
20
-
21
- handled, state = @records.snapshot_state_before(reflection.klass, id, boundary)
22
- return [handled, state ? [state] : []]
23
- end
24
- children(owner, reflection, boundary)
23
+ children(owner, reflection, boundary, ranked)
25
24
  end
26
25
 
27
26
  private
28
27
 
29
28
  # @rbs @records: PreparedRecordIndex
30
29
  # @rbs @edges: untyped
30
+ # @rbs @conditions: ScopeCondition::Cache
31
+
32
+ # A polymorphic target's class is known only once a record names it, so
33
+ # `target` reads its scope for each record instead.
34
+ #: (untyped, bool) -> bool
35
+ def supported?(reflection, ranked)
36
+ !reflection.foreign_key.is_a?(Array) &&
37
+ %i[belongs_to has_one has_many].include?(reflection.macro) &&
38
+ (reflection.polymorphic? || !@conditions.call(reflection, ranked: ranked).nil?)
39
+ end
40
+
41
+ #: (PreparedRecordState, untyped, bool, ?untyped) -> bool
42
+ def in_scope?(state, reflection, ranked, model_class = reflection.klass)
43
+ condition = @conditions.call(reflection, model_class, ranked: ranked) #: ScopeCondition
44
+ condition.matches?(state.attributes)
45
+ end
46
+
47
+ # A type that names no class, or a class whose scope cannot be read as
48
+ # conditions, is left to the record path, which raises for the first and
49
+ # reads the second through its association.
50
+ #: (PreparedRecordState, untyped, untyped, bool) -> [bool, Array[PreparedRecordState]]
51
+ def target(owner, reflection, boundary, ranked)
52
+ id = owner.attributes[reflection.foreign_key.to_s]
53
+ return [true, []] if id.nil?
54
+
55
+ model_class = target_class(owner, reflection)
56
+ return [false, []] unless model_class &&
57
+ @conditions.call(reflection, model_class, ranked: ranked)
31
58
 
32
- #: (untyped) -> bool
33
- def supported?(reflection)
34
- !reflection.options[:through] && !reflection.polymorphic? && reflection.scope.nil? &&
35
- !reflection.klass.default_scopes? && !reflection.foreign_key.is_a?(Array) &&
36
- %i[belongs_to has_one has_many].include?(reflection.macro)
59
+ handled, state = @records.snapshot_state_before(model_class, id, boundary)
60
+ [handled, state && in_scope?(state, reflection, ranked, model_class) ? [state] : []]
37
61
  end
38
62
 
39
- #: (PreparedRecordState, untyped, untyped) -> [bool, Array[PreparedRecordState]]
40
- def children(owner, reflection, boundary)
63
+ #: (PreparedRecordState, untyped) -> untyped
64
+ def target_class(owner, reflection)
65
+ return reflection.klass unless reflection.polymorphic?
66
+
67
+ AssociationTraversal.named_class(owner.attributes[reflection.foreign_type].to_s)
68
+ end
69
+
70
+ # The members of each join record the owner had at the boundary, as
71
+ # PreparedHistory#through_records reads them from records. Under
72
+ # `source_type:`, only join records of that type count. A has_many
73
+ # through reads its parts unranked, as its query does.
74
+ #: (PreparedRecordState, untyped, untyped, bool) -> [bool, Array[PreparedRecordState]]
75
+ def through(owner, reflection, boundary, ranked)
76
+ parts_ranked = ranked && !reflection.collection?
77
+ handled, joins = call(owner, reflection.through_reflection, boundary, ranked: parts_ranked)
78
+ return [false, []] unless handled
79
+
80
+ rows = [] #: Array[PreparedRecordState]
81
+ joins.each do |join|
82
+ next unless typed_join?(reflection, join)
83
+
84
+ handled, states = call(join, reflection.source_reflection, boundary, ranked: parts_ranked)
85
+ return [false, []] unless handled
86
+
87
+ rows.concat(states)
88
+ end
89
+ [true, through_members(reflection, rows, ranked)]
90
+ end
91
+
92
+ # The through's own scope applies after its parts' scopes, to each row,
93
+ # and a ranked read then keeps a record reached twice as one member.
94
+ #: (untyped, Array[PreparedRecordState], bool) -> Array[PreparedRecordState]
95
+ def through_members(reflection, rows, ranked)
96
+ condition = @conditions.call(reflection, ranked: ranked) #: ScopeCondition
97
+ members = condition.members(rows)
98
+ return members unless ranked
99
+
100
+ first_if_one(reflection, members.uniq { |state| identity(state) })
101
+ end
102
+
103
+ # A has_one keeps the first of its records.
104
+ #: (untyped, Array[PreparedRecordState]) -> Array[PreparedRecordState]
105
+ def first_if_one(reflection, states)
106
+ reflection.collection? ? states : states.first(1)
107
+ end
108
+
109
+ #: (untyped, PreparedRecordState) -> bool
110
+ def typed_join?(reflection, join)
111
+ AssociationTraversal.source_type_member?(reflection, join.attributes[reflection.foreign_type])
112
+ end
113
+
114
+ # A record reached through two join records is one member.
115
+ #: (PreparedRecordState) -> Array[untyped]
116
+ def identity(state)
117
+ model = state.model_class
118
+ [model.base_class.name, *Array(model.primary_key).map { |key| state.attributes[key].to_s }]
119
+ end
120
+
121
+ #: (PreparedRecordState, untyped, untyped, bool) -> [bool, Array[PreparedRecordState]]
122
+ def children(owner, reflection, boundary, ranked)
41
123
  selected = [] #: Array[PreparedRecordState]
42
124
  @edges.call(owner.model_class, reflection).each_value do |group|
43
125
  ids_for(group, owner).each do |id|
44
126
  handled, child = @records.snapshot_state_before(group.fetch(:model), id, boundary)
45
127
  return [false, []] unless handled
46
128
 
47
- selected << child if child && member?(child, owner, reflection)
129
+ selected << child if child && member?(child, owner, reflection, ranked)
48
130
  end
49
131
  end
50
- [true, reflection.collection? ? selected : selected.first(1)]
132
+ return [true, selected] unless ranked
133
+
134
+ condition = @conditions.call(reflection) #: ScopeCondition
135
+ [true, first_if_one(reflection, condition.rank(selected))]
51
136
  end
52
137
 
53
138
  #: (untyped, PreparedRecordState) -> Array[untyped]
54
139
  def ids_for(group, owner)
55
140
  owners = group[:owners]
56
- id = owner.attributes[owner.model_class.primary_key].to_s
57
141
  empty = [] #: Array[untyped]
58
- owners ? owners.fetch(id, empty) : group.fetch(:ids)
142
+ owners ? owners.fetch(owner_id(owner), empty) : group.fetch(:ids)
59
143
  end
60
144
 
61
- #: (PreparedRecordState, PreparedRecordState, untyped) -> bool
62
- def member?(child, owner, reflection)
63
- owner_id = owner.attributes[owner.model_class.primary_key].to_s
64
- return false unless child.attributes[reflection.foreign_key.to_s].to_s == owner_id
145
+ #: (PreparedRecordState, PreparedRecordState, untyped, bool) -> bool
146
+ def member?(child, owner, reflection, ranked)
147
+ return false unless child.attributes[reflection.foreign_key.to_s].to_s == owner_id(owner)
148
+ return false unless AssociationTraversal.sti_member?(reflection.klass, child.attributes)
149
+ return false unless in_scope?(child, reflection, ranked)
65
150
  return true unless reflection.options[:as]
66
151
 
67
152
  matching_type?(child, owner.model_class, reflection)
68
153
  end
69
154
 
155
+ #: (PreparedRecordState) -> String
156
+ def owner_id(owner)
157
+ owner.attributes[owner.model_class.primary_key].to_s
158
+ end
159
+
70
160
  #: (PreparedRecordState, untyped, untyped) -> bool
71
161
  def matching_type?(child, model, reflection)
72
162
  types = [model.name, model.base_class.name,
@@ -0,0 +1,83 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # The changes PaperTrail wrote with one version, typed by the version's model.
6
+ #
7
+ # A step's diff compares reconstructed states, so it also holds whatever was
8
+ # saved without a version before the next one was read. This is the other
9
+ # account of the same event: only what PaperTrail recorded for it. Comparing
10
+ # the two is how a caller tells an unrecorded write from the event's own edit.
11
+ #
12
+ # PaperTrail's `version.changeset` finds the model through `version.item`,
13
+ # which is a query per version and nothing at all once the record is deleted.
14
+ # The version already names its model, so neither is needed here.
15
+ class RecordedChanges
16
+ IGNORE_NAMES_REQUIRED = 'ignore: must be an array of strings or symbols; a version ' \
17
+ 'has no association path for paths: to match'
18
+ private_constant :IGNORE_NAMES_REQUIRED
19
+
20
+ #: (untyped, ignore: untyped) -> Hash[String, ValueChange]?
21
+ def self.call(version, ignore:)
22
+ new(version, ignore: ignore).call
23
+ end
24
+
25
+ #: (untyped, ignore: untyped) -> void
26
+ def initialize(version, ignore:)
27
+ @version = version
28
+ @ignore = ignore
29
+ end
30
+
31
+ #: () -> Hash[String, ValueChange]?
32
+ def call
33
+ raise InvalidEndpointError, 'expected a PaperTrail version' unless Endpoint.version?(@version)
34
+
35
+ ignored = ignored_names
36
+ return unless recorded?
37
+
38
+ model_class = Endpoint.model_class(@version)
39
+ changes = ActivityEventRecordResolver.new.deserialized_changeset(@version, model_class)
40
+ return if changes.nil?
41
+
42
+ value_changes(changes, Array(model_class.primary_key) + ignored)
43
+ end
44
+
45
+ private
46
+
47
+ # @rbs @version: untyped
48
+ # @rbs @ignore: untyped
49
+
50
+ # Validated before anything is read, so a bad option fails the same way
51
+ # whether or not this version happened to record changes. Subclasses of
52
+ # Array and String pass, as in other methods' `ignore:`; Symbol has none.
53
+ #: () -> Array[String]
54
+ def ignored_names
55
+ valid = @ignore.is_a?(Array) && @ignore.all? do |name|
56
+ name.is_a?(String) || name.instance_of?(Symbol)
57
+ end
58
+ raise ConfigurationError, IGNORE_NAMES_REQUIRED unless valid
59
+
60
+ @ignore.map(&:to_s)
61
+ end
62
+
63
+ # Without the column, or with it left empty for this version, nothing was
64
+ # recorded. That is not the same answer as a recorded empty changeset.
65
+ #: () -> bool
66
+ def recorded?
67
+ @version.class.column_names.include?('object_changes') && !@version.object_changes.nil?
68
+ end
69
+
70
+ # Primary keys identify the record rather than describe it, as in a diff.
71
+ #: (untyped, Array[String]) -> Hash[String, ValueChange]
72
+ def value_changes(changes, excluded)
73
+ recorded = {} #: Hash[String, ValueChange]
74
+ changes.each do |name, values|
75
+ key = name.to_s
76
+ next if excluded.include?(key)
77
+
78
+ recorded[key] = ValueChange.new(from: values.first, to: values.last)
79
+ end
80
+ recorded.sort.to_h.freeze
81
+ end
82
+ end
83
+ end
@@ -0,0 +1,53 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # The class a record had at one version, which decides the associations it
6
+ # can have. Without an `item_subtype` column PaperTrail stores only the base
7
+ # class, so an STI subclass is read from the stored inheritance column: the
8
+ # state before the change, or for a create, the value it was created with.
9
+ # A version that stored neither stays on the base class.
10
+ module RecordedClass
11
+ module_function
12
+
13
+ #: (untyped) -> untyped
14
+ def for(version)
15
+ model = Endpoint.model_class(version)
16
+ return model unless sti_base?(model)
17
+
18
+ type = stored_type(version, model).to_s
19
+ type.empty? ? model : model.sti_class_for(type)
20
+ rescue StandardError => e
21
+ raise unless subclass_not_found?(e)
22
+
23
+ raise InvalidEndpointError, "cannot resolve endpoint model: #{type}", cause: e
24
+ end
25
+
26
+ #: (untyped) -> bool
27
+ def sti_base?(model)
28
+ model.base_class == model && model.columns_hash.key?(model.inheritance_column.to_s)
29
+ end
30
+ private_class_method :sti_base?
31
+
32
+ #: (untyped, untyped) -> untyped
33
+ def stored_type(version, model)
34
+ column = model.inheritance_column.to_s
35
+ if version.object
36
+ attributes = version.object_deserialized
37
+ return attributes.is_a?(Hash) ? attributes[column] || attributes[column.to_sym] : nil
38
+ end
39
+
40
+ changes = ActivityEventRecordResolver.new.deserialized_changeset(version, model)
41
+ values = changes[column] if changes.respond_to?(:key?) && changes.key?(column)
42
+ values.last if values.is_a?(Array)
43
+ end
44
+ private_class_method :stored_type
45
+
46
+ #: (StandardError) -> bool
47
+ def subclass_not_found?(error)
48
+ active_record = Object.const_get(:ActiveRecord) #: untyped
49
+ error.is_a?(active_record.const_get(:SubclassNotFound))
50
+ end
51
+ private_class_method :subclass_not_found?
52
+ end
53
+ end
@@ -72,7 +72,7 @@ module PaperTrailDiff
72
72
  @steps = steps.freeze
73
73
  @context_version = context_version
74
74
  @mutations = (mutations || default_mutations).freeze
75
- @mutation_keys = Set.new(@mutations.map { |version| key(version) }).freeze
75
+ @mutation_keys = key_set(@mutations)
76
76
  freeze
77
77
  end
78
78
 
@@ -114,6 +114,15 @@ module PaperTrailDiff
114
114
  @versions.reject { |version| key(version) == context }
115
115
  end
116
116
 
117
+ # A Set only makes the lookup in `mutation?` fast; an Array would answer the
118
+ # same, which is why mutant leaves this alone.
119
+ # mutant:disable
120
+ #: (Array[untyped]) -> Set[Array[untyped]]
121
+ 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.
117
126
  #: (untyped) -> Array[untyped]
118
127
  def key(version)
119
128
  [version.class.name, version.id]