paper_trail_diff 0.15.0 → 0.16.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 (61) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +159 -1
  3. data/README.md +1 -1
  4. data/docs/performance.md +9 -0
  5. data/docs/reference.md +142 -28
  6. data/docs/testing.md +23 -3
  7. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -1
  8. data/lib/paper_trail_diff/activity_event_route_finder.rb +31 -0
  9. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +12 -1
  10. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +43 -25
  11. data/lib/paper_trail_diff/activity_timeline_builder.rb +6 -0
  12. data/lib/paper_trail_diff/analysis.rb +25 -6
  13. data/lib/paper_trail_diff/analysis_batch.rb +2 -2
  14. data/lib/paper_trail_diff/batched_root_analyzer.rb +6 -0
  15. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -16
  16. data/lib/paper_trail_diff/deleted_analysis_batch.rb +7 -3
  17. data/lib/paper_trail_diff/deleted_root_filter.rb +30 -8
  18. data/lib/paper_trail_diff/diagnostics.rb +7 -5
  19. data/lib/paper_trail_diff/paper_trail_adapter.rb +96 -59
  20. data/lib/paper_trail_diff/prepared_activity_index.rb +16 -12
  21. data/lib/paper_trail_diff/prepared_history.rb +11 -5
  22. data/lib/paper_trail_diff/prepared_history_loader.rb +1 -3
  23. data/lib/paper_trail_diff/prepared_record_index.rb +6 -2
  24. data/lib/paper_trail_diff/read_snapshot.rb +77 -0
  25. data/lib/paper_trail_diff/scope_condition.rb +85 -15
  26. data/lib/paper_trail_diff/scope_ranking.rb +11 -12
  27. data/lib/paper_trail_diff/scoped_analysis_builder.rb +17 -7
  28. data/lib/paper_trail_diff/scoped_root_selection.rb +11 -4
  29. data/lib/paper_trail_diff/time_range.rb +7 -6
  30. data/lib/paper_trail_diff/timeline_builder.rb +6 -0
  31. data/lib/paper_trail_diff/transaction_cut.rb +100 -41
  32. data/lib/paper_trail_diff/version.rb +1 -1
  33. data/lib/paper_trail_diff/version_boundary.rb +4 -2
  34. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +4 -1
  35. data/lib/paper_trail_diff.rb +7 -5
  36. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -0
  37. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +14 -0
  38. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -0
  39. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +21 -10
  40. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +4 -0
  41. data/sig/generated/paper_trail_diff/analysis.rbs +17 -5
  42. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +4 -0
  43. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +6 -0
  44. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +3 -0
  45. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +11 -3
  46. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +10 -0
  47. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +11 -4
  48. data/sig/generated/paper_trail_diff/prepared_history.rbs +6 -1
  49. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +2 -1
  50. data/sig/generated/paper_trail_diff/read_snapshot.rbs +43 -0
  51. data/sig/generated/paper_trail_diff/scope_condition.rbs +39 -7
  52. data/sig/generated/paper_trail_diff/scope_ranking.rbs +6 -6
  53. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +9 -2
  54. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +8 -3
  55. data/sig/generated/paper_trail_diff/time_range.rbs +4 -3
  56. data/sig/generated/paper_trail_diff/timeline_builder.rbs +4 -0
  57. data/sig/generated/paper_trail_diff/transaction_cut.rbs +46 -14
  58. data/sig/generated/paper_trail_diff/version_boundary.rbs +2 -0
  59. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +3 -0
  60. data/sig/generated/paper_trail_diff.rbs +2 -2
  61. metadata +7 -5
@@ -65,7 +65,7 @@ module PaperTrailDiff
65
65
  )
66
66
  unless routes.empty?
67
67
  delta = @record_resolver.snapshot_delta(event.version)
68
- return [false, nil] unless @collection_applier.safe?(routes, event.version, delta)
68
+ return [false, nil] unless collection_safe?(root_endpoint, tree, routes, event, delta)
69
69
 
70
70
  return @collection_applier.call(
71
71
  root_endpoint,
@@ -99,6 +99,17 @@ module PaperTrailDiff
99
99
 
100
100
  private :belongs_to_applier, :collection_applier, :collection_updater, :configure_appliers
101
101
 
102
+ # A through's membership follows the keys of the records it joins through
103
+ # or reaches, which a route to such a record elsewhere in the tree leaves
104
+ # alone, so the branch is read again instead.
105
+ #: (untyped, AssociationTree, Array[Array[untyped]], ActivityEvent, ActivitySnapshotDelta?) -> bool
106
+ def collection_safe?(root_endpoint, tree, routes, event, delta)
107
+ version = event.version
108
+ !@route_finder.through_part?(endpoint_model_class(root_endpoint), tree,
109
+ version.item_type.to_s) &&
110
+ @collection_applier.safe?(routes, version, delta)
111
+ end
112
+
102
113
  #: (untyped) -> untyped
103
114
  def record_after(version)
104
115
  @record_resolver.record_after(version, direct: true)
@@ -4,14 +4,15 @@
4
4
  module PaperTrailDiff
5
5
  # Advances scalar-only root events while retaining already reconstructed associations.
6
6
  class ActivityRootSnapshotRefresher
7
- #: (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, record_after: untyped, changeset: untyped, partial_snapshotter: untyped) -> void
7
+ #: (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, record_after: untyped, changeset: untyped, partial_snapshotter: untyped, ?record_transition: untyped) -> void
8
8
  def initialize( # rubocop:disable Metrics/ParameterLists
9
9
  tree:,
10
10
  traversal:,
11
11
  normalizer:,
12
12
  record_after:,
13
13
  changeset:,
14
- partial_snapshotter:
14
+ partial_snapshotter:,
15
+ record_transition: nil
15
16
  )
16
17
  @tree = tree
17
18
  @traversal = traversal
@@ -19,6 +20,7 @@ module PaperTrailDiff
19
20
  @record_after = record_after
20
21
  @changeset = changeset
21
22
  @partial_snapshotter = partial_snapshotter
23
+ @record_transition = record_transition
22
24
  @unsupported_branches = {} #: Hash[String, Array[String]]
23
25
  @relationship_reflections = {} #: Hash[String, Array[untyped]]
24
26
  end
@@ -34,21 +36,23 @@ module PaperTrailDiff
34
36
 
35
37
  version = event.version
36
38
  model_class = RecordedClass.for(version)
37
- return [false, nil] unless same_record?(previous, version)
39
+ return [false, nil] unless same_record?(previous, model_class, version)
38
40
 
39
- changes = @changeset.call(version, model_class)
40
- return [false, nil] unless changes.respond_to?(:each)
41
- return [false, nil] if changes.empty?
41
+ changed = changed_columns(version, model_class)
42
+ return [false, nil] if changed.empty?
43
+
44
+ # A change of STI class can change the associations themselves.
45
+ record = @record_after.call(version)
46
+ return [false, nil] unless record && recorded_class(record) == model_class
42
47
 
43
- branches = branches_to_refresh(model_class, changes)
48
+ branches = branches_to_refresh(model_class, changed)
44
49
  partial = nil #: RecordSnapshot?
45
50
  unless branches.empty?
46
51
  partial = @partial_snapshotter.call(root_endpoint, context_endpoint, branches)
47
52
  end
48
53
  return [false, nil] if !branches.empty? && !partial
49
54
 
50
- attributes = advanced_attributes(previous, version, changes)
51
- return [false, nil] unless attributes
55
+ attributes = @normalizer.attributes_for(record, tree: @tree, path: '')
52
56
 
53
57
  incoming_associations = {} #: snapshot_associations
54
58
  incoming_associations = partial.associations if partial
@@ -75,22 +79,35 @@ module PaperTrailDiff
75
79
  # @rbs @record_after: untyped
76
80
  # @rbs @changeset: untyped
77
81
  # @rbs @partial_snapshotter: untyped
82
+ # @rbs @record_transition: untyped
78
83
  # @rbs @unsupported_branches: Hash[String, Array[String]]
79
84
  # @rbs @relationship_reflections: Hash[String, Array[untyped]]
80
85
 
81
- #: (RecordSnapshot, untyped, untyped) -> snapshot_attributes?
82
- def advanced_attributes(previous, version, changes)
83
- return previous.attributes if changes.empty?
86
+ # The columns the version changed, from its changeset and from the states
87
+ # either side of it. The changeset leaves out columns that `only:` or
88
+ # `ignore:` exclude and keys written without a version, which the states
89
+ # hold.
90
+ #: (untyped, untyped) -> Array[String]
91
+ def changed_columns(version, model_class)
92
+ changes = @changeset.call(version, model_class)
93
+ names = changes.respond_to?(:each_key) ? changes.each_key.map(&:to_s) : [] #: Array[String]
94
+ transition = @record_transition&.call(version)
95
+ return names unless transition
84
96
 
85
- record = @record_after.call(version)
86
- return unless record
97
+ before, after = transition
98
+ names | (before.keys | after.keys).filter_map do |name|
99
+ name.to_s unless before[name] == after[name]
100
+ end
101
+ end
87
102
 
88
- @normalizer.attributes_for(record, tree: @tree, path: '')
103
+ #: (untyped) -> untyped
104
+ def recorded_class(record)
105
+ record.is_a?(PreparedRecordState) ? record.model_class : record.class
89
106
  end
90
107
 
91
- #: (untyped, untyped) -> Array[String]
92
- def branches_to_refresh(model_class, changes)
93
- (unsupported_branches(model_class) + changed_relationship_branches(model_class, changes))
108
+ #: (untyped, Array[String]) -> Array[String]
109
+ def branches_to_refresh(model_class, changed)
110
+ (unsupported_branches(model_class) + changed_relationship_branches(model_class, changed))
94
111
  .uniq
95
112
  .sort
96
113
  .freeze
@@ -122,15 +139,16 @@ module PaperTrailDiff
122
139
  false
123
140
  end
124
141
 
125
- #: (RecordSnapshot, untyped) -> bool
126
- def same_record?(snapshot, version)
127
- identity = Endpoint.identity(version)
128
- snapshot.type.to_s == identity.fetch(0) && snapshot.id.to_s == identity.fetch(1)
142
+ # The snapshot names the record's class, which for an STI subclass is not
143
+ # the base class the version names.
144
+ #: (RecordSnapshot, untyped, untyped) -> bool
145
+ def same_record?(snapshot, model_class, version)
146
+ snapshot.type.to_s == model_class.name.to_s &&
147
+ snapshot.id.to_s == Endpoint.identity(version).fetch(1)
129
148
  end
130
149
 
131
- #: (untyped, untyped) -> Array[String]
132
- def changed_relationship_branches(model_class, changes)
133
- changed = changes.each_key.map(&:to_s)
150
+ #: (untyped, Array[String]) -> Array[String]
151
+ def changed_relationship_branches(model_class, changed)
134
152
  root_relationship_reflections(model_class).filter_map do |reflection|
135
153
  reflection.name.to_s if changed.intersect?(relationship_columns(reflection))
136
154
  end
@@ -30,6 +30,12 @@ module PaperTrailDiff
30
30
  build_between_versions
31
31
  end
32
32
 
33
+ # The window the range covers once its edges have moved to transactions.
34
+ #: () -> TimeRange?
35
+ def window
36
+ @range.time_range
37
+ end
38
+
33
39
  # Builds the endpoint diff, the root timeline, and the activity from one
34
40
  # activity snapshot pass.
35
41
  #: () -> Analysis
@@ -9,30 +9,49 @@ module PaperTrailDiff
9
9
  attr_reader :activity_timeline #: Array[ActivityStep]?
10
10
  attr_reader :from_snapshot #: RecordSnapshot?
11
11
  attr_reader :to_snapshot #: RecordSnapshot?
12
+ # The time window the analysis covers, or nil without one. It is the
13
+ # window asked for unless a transaction crossed an edge, which moves the
14
+ # edge back to where that transaction began.
15
+ attr_reader :window #: Range[Time]?
12
16
 
13
17
  # The result for a record whose requested history contains no versions,
14
18
  # which is an empty history rather than a failed request. Its snapshots
15
19
  # are nil because no state was read, not because the record was absent:
16
- # reading one would rebuild the whole graph, per record in a batch.
17
- #: () -> Analysis
18
- def self.empty
20
+ # reading one would rebuild the whole graph, per record in a batch. Its
21
+ # activity timeline is empty when activity was asked for and nil when not,
22
+ # as a record with versions would have.
23
+ #: (?activity: bool) -> Analysis
24
+ def self.empty(activity: true)
19
25
  timeline = [] #: Array[Step]
20
26
  activity_timeline = [] #: Array[ActivityStep]
21
- new(diff: Diff.new, timeline: timeline, activity_timeline: activity_timeline)
27
+ new(diff: Diff.new, timeline: timeline, activity_timeline: (activity_timeline if activity))
22
28
  end
23
29
 
24
30
  # The reconstructed states the diff was taken between. A report that has to
25
31
  # render unchanged columns needs the whole final state, not only what moved.
26
- #: (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
27
- def initialize(diff:, timeline:, activity_timeline: nil, from_snapshot: nil, to_snapshot: nil)
32
+ #: (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?window: Range[Time]?) -> void
33
+ def initialize( # rubocop:disable Metrics/ParameterLists
34
+ diff:, timeline:, activity_timeline: nil, from_snapshot: nil, to_snapshot: nil, window: nil
35
+ )
28
36
  @diff = diff
29
37
  @timeline = timeline.dup.freeze
30
38
  @activity_timeline = activity_timeline&.dup&.freeze
31
39
  @from_snapshot = from_snapshot
32
40
  @to_snapshot = to_snapshot
41
+ @window = window
33
42
  freeze
34
43
  end
35
44
 
45
+ # The same result for the window it was read in, which the caller knows
46
+ # once it has moved the window's edges to transactions.
47
+ #: (TimeRange?) -> Analysis
48
+ def with_window(range)
49
+ self.class.new(
50
+ diff: diff, timeline: timeline, activity_timeline: activity_timeline,
51
+ from_snapshot: from_snapshot, to_snapshot: to_snapshot, window: range&.to_range
52
+ )
53
+ end
54
+
36
55
  # Every activity step's rows, in time order. Only the activity timeline says
37
56
  # who made each change, so an analysis built without it has no rows to give.
38
57
  #: () -> Array[ChangeRow]
@@ -103,9 +103,9 @@ module PaperTrailDiff
103
103
  # on current state, where its descendants may still have moved.
104
104
  #: (untyped, RootVersionPlan, TimeRange?) -> Analysis
105
105
  def analysis_for(record, plan, window)
106
- return Analysis.empty if plan.empty? && !plan.closing_record
106
+ return @analyzer.empty.with_window(window) if plan.empty? && !plan.closing_record
107
107
 
108
- @analyzer.call(record, plan, window)
108
+ @analyzer.call(record, plan, window).with_window(window)
109
109
  end
110
110
  end
111
111
  end
@@ -32,6 +32,12 @@ module PaperTrailDiff
32
32
  ).analyze
33
33
  end
34
34
 
35
+ # The result for a root with nothing to read.
36
+ #: () -> Analysis
37
+ def empty
38
+ Analysis.empty(activity: @activity)
39
+ end
40
+
35
41
  private
36
42
 
37
43
  # @rbs @tree: AssociationTree
@@ -35,7 +35,8 @@ module PaperTrailDiff
35
35
  tree: tree, traversal: traversal, normalizer: normalizer,
36
36
  record_after: @event_refresher.method(:record_after),
37
37
  changeset: @event_refresher.method(:deserialized_changeset),
38
- partial_snapshotter: method(:partial_snapshot)
38
+ partial_snapshotter: method(:partial_snapshot),
39
+ record_transition: record_transition
39
40
  )
40
41
  end
41
42
 
@@ -53,7 +54,7 @@ module PaperTrailDiff
53
54
  end
54
55
 
55
56
  #: (untyped, untyped, RecordSnapshot?, Array[String], ?event: ActivityEvent?, ?isolated: bool) -> RecordSnapshot?
56
- def call( # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
57
+ def call( # rubocop:disable Metrics/ParameterLists
57
58
  root_endpoint,
58
59
  context_endpoint,
59
60
  previous_snapshot,
@@ -62,24 +63,16 @@ module PaperTrailDiff
62
63
  isolated: false
63
64
  )
64
65
  return full_snapshot(root_endpoint, context_endpoint) unless previous_snapshot
66
+
67
+ branches = with_habtm(root_endpoint, context_endpoint, branches)
65
68
  if isolated && event && branches.length > 1
66
- return refresh_independent_branches(
67
- root_endpoint,
68
- context_endpoint,
69
- previous_snapshot,
70
- branches,
71
- event
72
- )
69
+ return refresh_independent_branches(root_endpoint, context_endpoint, previous_snapshot,
70
+ branches, event)
73
71
  end
74
72
 
75
73
  endpoints = [root_endpoint, context_endpoint]
76
- handled, incremental = incremental_event(
77
- endpoints,
78
- previous_snapshot,
79
- branches,
80
- event,
81
- isolated
82
- )
74
+ handled, incremental = incremental_event(endpoints, previous_snapshot, branches, event,
75
+ isolated)
83
76
  return incremental if handled
84
77
 
85
78
  partial = partial_snapshot(root_endpoint, context_endpoint, branches)
@@ -100,6 +93,16 @@ module PaperTrailDiff
100
93
  # @rbs @event_refresher: ActivityEventSnapshotRefresher
101
94
  # @rbs @root_refresher: ActivityRootSnapshotRefresher
102
95
 
96
+ # A root version's HABTM members include any created earlier in its
97
+ # transaction. A range ending at that version leaves those creations out
98
+ # as events, so the branch is read again there, whatever event led to it.
99
+ #: (untyped, untyped, Array[String]) -> Array[String]
100
+ def with_habtm(root_endpoint, context_endpoint, branches)
101
+ root = Endpoint.version?(root_endpoint) &&
102
+ VersionBoundary.same_version?(root_endpoint, context_endpoint)
103
+ root ? branches | @traversal.habtm_paths(RecordedClass.for(root_endpoint)) : branches
104
+ end
105
+
103
106
  #: (Array[untyped], RecordSnapshot, Array[String], ActivityEvent?, bool) -> [bool, RecordSnapshot?]
104
107
  def incremental_event(endpoints, previous, branches, event, isolated)
105
108
  return [false, nil] unless isolated
@@ -29,15 +29,19 @@ module PaperTrailDiff
29
29
  prepare(records, selected, windows)
30
30
  analyses = records.to_h do |record|
31
31
  key = Endpoint.identity(record)
32
- plan = selected.fetch(key)
33
- window = windows.fetch(key, @time_range)
34
- [key, plan.empty? ? Analysis.empty : @analyzer.call(record, plan, window)]
32
+ [key, analysis_for(record, selected.fetch(key), windows.fetch(key, @time_range))]
35
33
  end
36
34
  with_unavailable(analyses)
37
35
  end
38
36
 
39
37
  private
40
38
 
39
+ #: (untyped, RootVersionPlan, TimeRange?) -> Analysis
40
+ def analysis_for(record, plan, window)
41
+ analysis = plan.empty? ? @analyzer.empty : @analyzer.call(record, plan, window)
42
+ analysis.with_window(window)
43
+ end
44
+
41
45
  #: (Hash[Array[String], Analysis]) -> Hash[Array[String], Analysis?]
42
46
  def with_unavailable(analyses)
43
47
  @identities.to_h { |key| [Support.immutable_copy(key), analyses[key]] }.freeze
@@ -7,6 +7,9 @@ module PaperTrailDiff
7
7
  # table, where a destroyed root has no row, so without this a report on one
8
8
  # account's records would include every account's deletions.
9
9
  class DeletedRootFilter
10
+ SLICE = 500
11
+ private_constant :SLICE
12
+
10
13
  #: (untyped) -> void
11
14
  def initialize(relation)
12
15
  @relation = relation
@@ -14,19 +17,31 @@ module PaperTrailDiff
14
17
  unless condition
15
18
  raise ConfigurationError,
16
19
  '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"
20
+ "conditions must be equality, IN, NULL, or range tests on #{model.name}'s " \
21
+ 'own columns, and a range or a text comparison must be on a column whose ' \
22
+ 'values compare in Ruby as the database compares them, as for an ' \
23
+ 'association scope; select deleted records some other way'
19
24
  end
20
25
 
21
26
  @condition = condition
22
27
  @loader = DirectRecordStateLoader.new
23
28
  end
24
29
 
30
+ # nil when the relation's conditions cannot be read.
31
+ #: (untyped) -> DeletedRootFilter?
32
+ def self.readable(relation)
33
+ new(relation)
34
+ rescue ConfigurationError
35
+ nil
36
+ end
37
+
25
38
  # 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.
39
+ # and stays, as it has no state to report either, unless the relation
40
+ # selects nothing. One whose destroy recorded no state is left out.
28
41
  #: (Array[Array[String]]) -> Array[Array[String]]
29
42
  def call(identities)
43
+ return [] if @condition.none?
44
+
30
45
  states = destroyed_states(identities.map(&:last))
31
46
  identities.select do |identity|
32
47
  id = identity.last
@@ -55,13 +70,20 @@ module PaperTrailDiff
55
70
  AssociationTraversal.sti_member?(model, attributes) && @condition.matches?(attributes)
56
71
  end
57
72
 
58
- # The state each root held before its latest destroy.
73
+ # The state each root held before its latest destroy, read in slices: a
74
+ # report lists every deleted root it reached, and SQL Server cannot plan an
75
+ # IN list of thousands.
59
76
  #: (Array[String]) -> Hash[String, Hash[String, untyped]?]
60
77
  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)]
78
+ states = {} #: Hash[String, Hash[String, untyped]?]
79
+ ids.each_slice(SLICE) do |slice|
80
+ destroys = VersionQuery.for_items(model, slice).where(event: 'destroy')
81
+ VersionQuery.chronological(destroys).each do |version|
82
+ states[version.item_id.to_s] =
83
+ @loader.call(version)&.attributes || reified_attributes(version)
84
+ end
64
85
  end
86
+ states
65
87
  end
66
88
 
67
89
  # Read directly, with a column `skip:` left out of history as its default,
@@ -88,11 +88,13 @@ module PaperTrailDiff
88
88
  def call
89
89
  unless @versions.empty?
90
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?
91
+ ReadSnapshot.call([model_class]) do
92
+ # Runs whether or not associations are selected: unorderable versions
93
+ # corrupt a scalar timeline just as surely, and a report that inspected
94
+ # nothing has no business answering `ok?`.
95
+ inspect_version_sequence(model_class)
96
+ inspect_associations(model_class) unless @tree.empty?
97
+ end
96
98
  end
97
99
  DiagnosticReport.new(issues: @issues)
98
100
  end
@@ -35,14 +35,16 @@ module PaperTrailDiff
35
35
  Instrumentation.instrument('compare', payload) do
36
36
  Endpoint.validate_pair!(from_endpoint, to_endpoint)
37
37
  notify_ambiguous_association_boundary(from_endpoint, to_endpoint)
38
- if @association_tree.empty?
39
- Engine.compare(snapshot_for_endpoint(from_endpoint), snapshot_for_endpoint(to_endpoint))
40
- else
41
- # Prepared history orders versions that share a timestamp and finds
42
- # children that later moved away; reading associations straight from
43
- # PT-AT would resolve them by time alone and miss those children.
44
- comparison_batch([{ from: from_endpoint, to: to_endpoint }],
45
- preparer: @traversal_preparer.method(:call)).call.values.fetch(0)
38
+ ReadSnapshot.call([from_endpoint, to_endpoint]) do
39
+ if @association_tree.empty?
40
+ Engine.compare(snapshot_for_endpoint(from_endpoint), snapshot_for_endpoint(to_endpoint))
41
+ else
42
+ # Prepared history orders versions that share a timestamp and finds
43
+ # children that later moved away; reading associations straight from
44
+ # PT-AT would resolve them by time alone and miss those children.
45
+ comparison_batch([{ from: from_endpoint, to: to_endpoint }],
46
+ preparer: @traversal_preparer.method(:call)).call.values.fetch(0)
47
+ end
46
48
  end
47
49
  end
48
50
  end
@@ -53,24 +55,28 @@ module PaperTrailDiff
53
55
  count = comparisons.is_a?(Array) ? comparisons.length : 0
54
56
  payload = @instrumentation_payload.merge(comparison_count: count)
55
57
  Instrumentation.instrument('compare_many', payload) do
56
- comparison_batch(comparisons, preparer: @traversal_preparer.method(:call)).call
58
+ ReadSnapshot.call(comparison_endpoints(comparisons)) do
59
+ comparison_batch(comparisons, preparer: @traversal_preparer.method(:call)).call
60
+ end
57
61
  end
58
62
  end
59
63
 
60
64
  #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped) -> Array[Step]
61
65
  def timeline(record, from:, to:, within:, version_scope: nil)
62
66
  Endpoint.validate_root!(record)
63
- @traversal_preparer.call(record.class, historical: true)
64
- from, to = default_range(record, from, to, within)
65
- TimelineBuilder.new(
66
- record,
67
- from: from,
68
- to: to,
69
- within: within,
70
- version_scope: version_scope,
71
- live_endpoint: live_endpoint_for(record, within),
72
- snapshotter: @timeline_snapshotter
73
- ).build
67
+ ReadSnapshot.call([record]) do
68
+ @traversal_preparer.call(record.class, historical: true)
69
+ from, to = default_range(record, from, to, within)
70
+ TimelineBuilder.new(
71
+ record,
72
+ from: from,
73
+ to: to,
74
+ within: within,
75
+ version_scope: version_scope,
76
+ live_endpoint: live_endpoint_for(record, within),
77
+ snapshotter: @timeline_snapshotter
78
+ ).build
79
+ end
74
80
  end
75
81
 
76
82
  #: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
@@ -78,13 +84,15 @@ module PaperTrailDiff
78
84
  Endpoint.validate_root!(record)
79
85
  payload = model_payload(record)
80
86
  Instrumentation.instrument('activity_timeline', payload) do
81
- @traversal_preparer.call(record.class, historical: true)
82
- from, to = default_range(record, from, to, within)
83
- live = live_endpoint_for(record, within)
84
- steps = activity_builder(
85
- record, from: from, to: to, within: within, version_scope: version_scope,
86
- live_endpoint: live, view: activity_view(true, snapshots, group)
87
- ).build
87
+ steps = ReadSnapshot.call([record]) do
88
+ @traversal_preparer.call(record.class, historical: true)
89
+ from, to = default_range(record, from, to, within)
90
+ live = live_endpoint_for(record, within)
91
+ activity_builder(
92
+ record, from: from, to: to, within: within, version_scope: version_scope,
93
+ live_endpoint: live, view: activity_view(true, snapshots, group)
94
+ ).build
95
+ end
88
96
  payload[:step_count] = steps.length
89
97
  steps
90
98
  end
@@ -94,27 +102,19 @@ module PaperTrailDiff
94
102
  def analyze(record, from:, to:, within:, activity: false, version_scope: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
95
103
  view = activity_view(activity, snapshots, group)
96
104
  Endpoint.validate_root!(record)
97
- @traversal_preparer.call(record.class, historical: true)
98
- from, to = default_range(record, from, to, within)
99
- live = live_endpoint_for(record, within)
100
- if activity
101
- return activity_builder(
102
- record, from: from, to: to, within: within, version_scope: version_scope,
103
- live_endpoint: live, view: view
104
- ).analyze
105
+ ReadSnapshot.call([record]) do
106
+ analyze_record(record, from: from, to: to, within: within, activity: activity,
107
+ version_scope: version_scope, view: view)
105
108
  end
106
-
107
- TimelineBuilder.new(
108
- record, from: from, to: to, within: within, version_scope: version_scope,
109
- live_endpoint: live, snapshotter: @timeline_snapshotter
110
- ).analyze
111
109
  end
112
110
 
113
111
  # Analyzes many roots over one shared range, preparing their history once.
114
112
  #: (Array[untyped], within: untyped, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?) -> Hash[identity, Analysis]
115
113
  def analyze_many(records, within:, activity: false, version_scope: nil, snapshots: false, group: nil) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
116
- analyze_batch(records, within: within, activity: activity, version_scope: version_scope,
117
- view: activity_view(activity, snapshots, group))
114
+ ReadSnapshot.call(records.is_a?(Array) ? records : []) do
115
+ analyze_batch(records, within: within, activity: activity, version_scope: version_scope,
116
+ view: activity_view(activity, snapshots, group))
117
+ end
118
118
  end
119
119
 
120
120
  # Selects the roots from a relation before running the ordinary batch, so a
@@ -124,23 +124,13 @@ module PaperTrailDiff
124
124
  #: (untyped, limit: Integer?, within: untyped, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool) -> ScopedAnalysis
125
125
  def analyze_scope(scope, limit:, within:, activity: false, version_scope: nil, snapshots: false, group: nil, historical_filter: nil, max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, include_deleted: false) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
126
126
  view = activity_view(activity, snapshots, group)
127
- check_scope(scope)
128
- # @type var options: report_options
129
- options = { within: within, activity: activity, version_scope: version_scope, view: view }
130
- ScopedAnalysisBuilder.new(
131
- scope, limit: limit, within: within, historical_filter: historical_filter,
132
- max_filter_versions: max_filter_versions, include_deleted: include_deleted,
133
- analyzer: lambda { |records|
134
- analyze_batch(records, within: within, activity: activity,
135
- version_scope: version_scope, view: view)
136
- },
137
- deleted_analyzer: lambda { |identities|
138
- analyze_deleted(scope.all.model, identities, options)
139
- },
140
- # Checkpoints compare a root's own versions, so only activity can
141
- # report a window in which just its associations changed.
142
- activity_tree: (@association_tree if activity)
143
- ).call
127
+ ReadSnapshot.call([scope]) do
128
+ check_scope(scope)
129
+ scoped_builder(scope, limit: limit, within: within, activity: activity,
130
+ version_scope: version_scope, historical_filter: historical_filter,
131
+ max_filter_versions: max_filter_versions,
132
+ include_deleted: include_deleted, view: view).call
133
+ end
144
134
  end
145
135
 
146
136
  private
@@ -156,6 +146,25 @@ module PaperTrailDiff
156
146
  @instrumentation_payload.merge(model_type: record.class.base_class.name.to_s)
157
147
  end
158
148
 
149
+ #: (untyped, from: untyped, to: untyped, within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Analysis
150
+ def analyze_record(record, from:, to:, within:, activity:, version_scope:, view:) # rubocop:disable Metrics/ParameterLists
151
+ @traversal_preparer.call(record.class, historical: true)
152
+ from, to = default_range(record, from, to, within)
153
+ live = live_endpoint_for(record, within)
154
+ builder = if activity
155
+ activity_builder(
156
+ record, from: from, to: to, within: within, version_scope: version_scope,
157
+ live_endpoint: live, view: view
158
+ )
159
+ else
160
+ TimelineBuilder.new(
161
+ record, from: from, to: to, within: within, version_scope: version_scope,
162
+ live_endpoint: live, snapshotter: @timeline_snapshotter
163
+ )
164
+ end
165
+ builder.analyze.with_window(builder.window)
166
+ end
167
+
159
168
  #: (Array[untyped], within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Hash[identity, Analysis]
160
169
  def analyze_batch(records, within:, activity:, version_scope:, view:)
161
170
  count = records.is_a?(Array) ? records.length : 0
@@ -181,6 +190,14 @@ module PaperTrailDiff
181
190
  @traversal_preparer.call(scope.all.model, historical: true)
182
191
  end
183
192
 
193
+ # The endpoints of the hash comparisons. Anything else is left for the batch to refuse.
194
+ #: (untyped) -> Array[untyped]
195
+ def comparison_endpoints(comparisons)
196
+ return [] unless comparisons.is_a?(Array)
197
+
198
+ comparisons.grep(Hash).flat_map(&:values)
199
+ end
200
+
184
201
  #: (Array[comparison_input], preparer: untyped) -> ComparisonBatch
185
202
  def comparison_batch(comparisons, preparer:)
186
203
  ComparisonBatch.new(
@@ -214,6 +231,26 @@ module PaperTrailDiff
214
231
  ).call
215
232
  end
216
233
 
234
+ #: (untyped, limit: Integer?, within: untyped, activity: bool, version_scope: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, view: ActivityView) -> ScopedAnalysisBuilder
235
+ def scoped_builder(scope, limit:, within:, activity:, version_scope:, historical_filter:, max_filter_versions:, include_deleted:, view:) # rubocop:disable Metrics/ParameterLists, Layout/LineLength
236
+ # @type var options: report_options
237
+ options = { within: within, activity: activity, version_scope: version_scope, view: view }
238
+ ScopedAnalysisBuilder.new(
239
+ scope, limit: limit, within: within, historical_filter: historical_filter,
240
+ max_filter_versions: max_filter_versions, include_deleted: include_deleted,
241
+ analyzer: lambda { |records|
242
+ analyze_batch(records, within: within, activity: activity,
243
+ version_scope: version_scope, view: view)
244
+ },
245
+ deleted_analyzer: lambda { |identities|
246
+ analyze_deleted(scope.all.model, identities, options)
247
+ },
248
+ # Checkpoints compare a root's own versions, so only activity can
249
+ # report a window in which just its associations changed.
250
+ activity_tree: (@association_tree if activity), version_scope: version_scope
251
+ )
252
+ end
253
+
217
254
  # @rbs @association_tree: AssociationTree
218
255
  # @rbs @live_endpoints: LiveEndpointProvider
219
256
  # @rbs @instrumentation_payload: Hash[Symbol, untyped]