paper_trail_diff 0.14.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 (150) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +501 -0
  3. data/QUICKSTART.md +21 -4
  4. data/README.md +59 -56
  5. data/docs/architecture.md +32 -11
  6. data/docs/performance.md +125 -391
  7. data/docs/reference.md +470 -117
  8. data/docs/testing.md +83 -7
  9. data/lib/paper_trail_diff/activity_boundary.rb +83 -26
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -1
  12. data/lib/paper_trail_diff/activity_event.rb +41 -10
  13. data/lib/paper_trail_diff/activity_event_route_finder.rb +31 -0
  14. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +12 -1
  15. data/lib/paper_trail_diff/activity_history.rb +34 -9
  16. data/lib/paper_trail_diff/activity_range.rb +18 -3
  17. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +43 -25
  18. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
  19. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +5 -5
  20. data/lib/paper_trail_diff/activity_timeline_builder.rb +272 -111
  21. data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
  22. data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
  23. data/lib/paper_trail_diff/activity_version_collector.rb +7 -5
  24. data/lib/paper_trail_diff/activity_view.rb +69 -0
  25. data/lib/paper_trail_diff/analysis.rb +37 -6
  26. data/lib/paper_trail_diff/analysis_batch.rb +25 -31
  27. data/lib/paper_trail_diff/approximate_paths.rb +48 -0
  28. data/lib/paper_trail_diff/association_activity_edge.rb +6 -6
  29. data/lib/paper_trail_diff/association_discovery.rb +9 -1
  30. data/lib/paper_trail_diff/association_key.rb +56 -0
  31. data/lib/paper_trail_diff/association_traversal.rb +13 -4
  32. data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
  33. data/lib/paper_trail_diff/batch_preload.rb +53 -0
  34. data/lib/paper_trail_diff/batched_root_analyzer.rb +18 -14
  35. data/lib/paper_trail_diff/batched_root_versions.rb +38 -14
  36. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -16
  37. data/lib/paper_trail_diff/change_row.rb +133 -0
  38. data/lib/paper_trail_diff/collection_comparator.rb +5 -32
  39. data/lib/paper_trail_diff/configuration.rb +35 -12
  40. data/lib/paper_trail_diff/deleted_analysis_batch.rb +23 -19
  41. data/lib/paper_trail_diff/deleted_root_filter.rb +101 -0
  42. data/lib/paper_trail_diff/deprecation.rb +61 -0
  43. data/lib/paper_trail_diff/diagnostics.rb +86 -99
  44. data/lib/paper_trail_diff/endpoint.rb +26 -3
  45. data/lib/paper_trail_diff/errors.rb +3 -1
  46. data/lib/paper_trail_diff/fallback_paths.rb +38 -0
  47. data/lib/paper_trail_diff/historical_association_reifier.rb +2 -4
  48. data/lib/paper_trail_diff/historical_filter.rb +19 -10
  49. data/lib/paper_trail_diff/historical_snapshot_store.rb +57 -67
  50. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -35
  51. data/lib/paper_trail_diff/nested_comparator.rb +19 -18
  52. data/lib/paper_trail_diff/paper_trail_adapter.rb +198 -166
  53. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +13 -1
  54. data/lib/paper_trail_diff/prepared_activity_index.rb +17 -13
  55. data/lib/paper_trail_diff/prepared_edge_loader.rb +2 -1
  56. data/lib/paper_trail_diff/prepared_history.rb +15 -1
  57. data/lib/paper_trail_diff/prepared_history_loader.rb +2 -3
  58. data/lib/paper_trail_diff/prepared_record_index.rb +42 -7
  59. data/lib/paper_trail_diff/read_snapshot.rb +77 -0
  60. data/lib/paper_trail_diff/root_version_selection.rb +4 -2
  61. data/lib/paper_trail_diff/scope_condition.rb +157 -32
  62. data/lib/paper_trail_diff/scope_ranking.rb +23 -14
  63. data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
  64. data/lib/paper_trail_diff/scoped_analysis_builder.rb +29 -11
  65. data/lib/paper_trail_diff/scoped_root_selection.rb +29 -16
  66. data/lib/paper_trail_diff/snapshot.rb +16 -1
  67. data/lib/paper_trail_diff/support.rb +29 -2
  68. data/lib/paper_trail_diff/time_range.rb +39 -16
  69. data/lib/paper_trail_diff/timeline_builder.rb +13 -7
  70. data/lib/paper_trail_diff/timeline_range.rb +9 -1
  71. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
  72. data/lib/paper_trail_diff/transaction_cut.rb +240 -0
  73. data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
  74. data/lib/paper_trail_diff/version.rb +1 -1
  75. data/lib/paper_trail_diff/version_boundary.rb +41 -10
  76. data/lib/paper_trail_diff/version_query.rb +34 -10
  77. data/lib/paper_trail_diff/version_scope_filter.rb +9 -10
  78. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +35 -17
  79. data/lib/paper_trail_diff/version_table.rb +60 -0
  80. data/lib/paper_trail_diff.rb +101 -57
  81. data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
  82. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -0
  83. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
  84. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +14 -0
  85. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -0
  86. data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
  87. data/sig/generated/paper_trail_diff/activity_range.rbs +9 -2
  88. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +21 -10
  89. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
  90. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -30
  91. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
  92. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +2 -0
  93. data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
  94. data/sig/generated/paper_trail_diff/analysis.rbs +24 -5
  95. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
  96. data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
  97. data/sig/generated/paper_trail_diff/association_discovery.rbs +5 -0
  98. data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
  99. data/sig/generated/paper_trail_diff/association_traversal.rbs +4 -0
  100. data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
  101. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -10
  102. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -4
  103. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +6 -0
  104. data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
  105. data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
  106. data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
  107. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -8
  108. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +56 -0
  109. data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
  110. data/sig/generated/paper_trail_diff/diagnostics.rbs +37 -30
  111. data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
  112. data/sig/generated/paper_trail_diff/errors.rbs +3 -1
  113. data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
  114. data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
  115. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +33 -28
  116. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +0 -15
  117. data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
  118. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +64 -52
  119. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
  120. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +11 -4
  121. data/sig/generated/paper_trail_diff/prepared_history.rbs +10 -0
  122. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +20 -2
  123. data/sig/generated/paper_trail_diff/read_snapshot.rbs +43 -0
  124. data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
  125. data/sig/generated/paper_trail_diff/scope_condition.rbs +81 -15
  126. data/sig/generated/paper_trail_diff/scope_ranking.rbs +14 -6
  127. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
  128. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +14 -2
  129. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +16 -7
  130. data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
  131. data/sig/generated/paper_trail_diff/support.rbs +15 -0
  132. data/sig/generated/paper_trail_diff/time_range.rbs +24 -9
  133. data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
  134. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
  135. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
  136. data/sig/generated/paper_trail_diff/transaction_cut.rbs +126 -0
  137. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
  138. data/sig/generated/paper_trail_diff/version_boundary.rbs +22 -3
  139. data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
  140. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +4 -5
  141. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +19 -9
  142. data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
  143. data/sig/generated/paper_trail_diff.rbs +29 -26
  144. metadata +49 -11
  145. data/lib/paper_trail_diff/activity_grouping.rb +0 -38
  146. data/lib/paper_trail_diff/batch_safety.rb +0 -63
  147. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -223
  148. data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
  149. data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -30
  150. data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
@@ -0,0 +1,42 @@
1
+ # Generated from lib/paper_trail_diff/activity_view.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # How a request presents its activity steps: whether they keep their
5
+ # snapshots, whether a transaction's steps merge into one, and which of
6
+ # their versions' recorded changes they carry. Built and checked once per
7
+ # request, and read the same way by both activity builders, or the same
8
+ # history would read differently depending on how it was asked for.
9
+ class ActivityView
10
+ # Options only an activity view uses are refused without one.
11
+ # : (activity: bool, snapshots: bool, group: Symbol?, recorded: IgnorePolicy?) -> ActivityView
12
+ def self.build: (activity: bool, snapshots: bool, group: Symbol?, recorded: IgnorePolicy?) -> ActivityView
13
+
14
+ # : (?snapshots: bool, ?group: Symbol?, ?recorded: IgnorePolicy?) -> void
15
+ def initialize: (?snapshots: bool, ?group: Symbol?, ?recorded: IgnorePolicy?) -> void
16
+
17
+ # Merging a group compares its outer states, so the snapshots must survive
18
+ # the build even when the caller did not ask to keep them.
19
+ # : () -> bool
20
+ def retain?: () -> bool
21
+
22
+ # The attributes a boundary's version recorded, when they were asked for.
23
+ # : (root: bool) -> Array[String]?
24
+ def recorded_attributes: (root: bool) -> Array[String]?
25
+
26
+ # Applied last, to finished steps, so grouping sees the same timeline the
27
+ # caller would otherwise have received.
28
+ # : (Array[ActivityStep]) -> Array[ActivityStep]
29
+ def present: (Array[ActivityStep]) -> Array[ActivityStep]
30
+
31
+ private
32
+
33
+ @group: Symbol?
34
+
35
+ @recorded: IgnorePolicy?
36
+
37
+ @snapshots: bool
38
+
39
+ # : () -> bool
40
+ def grouping?: () -> bool
41
+ end
42
+ end
@@ -13,15 +13,34 @@ module PaperTrailDiff
13
13
 
14
14
  attr_reader to_snapshot: RecordSnapshot?
15
15
 
16
+ # The time window the analysis covers, or nil without one. It is the
17
+ # window asked for unless a transaction crossed an edge, which moves the
18
+ # edge back to where that transaction began.
19
+ attr_reader window: Range[Time]?
20
+
16
21
  # The result for a record whose requested history contains no versions,
17
- # which is an empty history rather than a failed request.
18
- # : () -> Analysis
19
- def self.empty: () -> Analysis
22
+ # which is an empty history rather than a failed request. Its snapshots
23
+ # are nil because no state was read, not because the record was absent:
24
+ # reading one would rebuild the whole graph, per record in a batch. Its
25
+ # activity timeline is empty when activity was asked for and nil when not,
26
+ # as a record with versions would have.
27
+ # : (?activity: bool) -> Analysis
28
+ def self.empty: (?activity: bool) -> Analysis
20
29
 
21
30
  # The reconstructed states the diff was taken between. A report that has to
22
31
  # render unchanged columns needs the whole final state, not only what moved.
23
- # : (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
24
- def initialize: (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
32
+ # : (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?window: Range[Time]?) -> void
33
+ def initialize: (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?window: Range[Time]?) -> void
34
+
35
+ # The same result for the window it was read in, which the caller knows
36
+ # once it has moved the window's edges to transactions.
37
+ # : (TimeRange?) -> Analysis
38
+ def with_window: (TimeRange?) -> Analysis
39
+
40
+ # Every activity step's rows, in time order. Only the activity timeline says
41
+ # who made each change, so an analysis built without it has no rows to give.
42
+ # : () -> Array[ChangeRow]
43
+ def change_rows: () -> Array[ChangeRow]
25
44
 
26
45
  # Reconstructed endpoint states are opt-in, because they carry the whole
27
46
  # selected graph whether or not anything changed, which dwarfs the rest of
@@ -5,8 +5,8 @@ module PaperTrailDiff
5
5
  # versions and preparing their association history once for the whole batch
6
6
  # rather than once per root.
7
7
  class AnalysisBatch
8
- # : (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped, ?close_on_current: bool, ?context_required: bool) -> void
9
- def initialize: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped, ?close_on_current: bool, ?context_required: bool) -> void
8
+ # : (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped, ?context_required: bool) -> void
9
+ def initialize: (Array[untyped], time_range: TimeRange?, live_loader: untyped, history_preparer: untyped, analyzer: untyped, ?version_scope: untyped, ?context_required: bool) -> void
10
10
 
11
11
  # : () -> Hash[identity, Analysis]
12
12
  def call: () -> Hash[identity, Analysis]
@@ -15,8 +15,6 @@ module PaperTrailDiff
15
15
 
16
16
  @analyzer: untyped
17
17
 
18
- @close_on_current: bool
19
-
20
18
  @context_required: bool
21
19
 
22
20
  @history_preparer: untyped
@@ -29,11 +27,6 @@ module PaperTrailDiff
29
27
 
30
28
  @version_scope: untyped
31
29
 
32
- # A filter is a callable that narrows the version relation, so it is checked
33
- # up front rather than failing partway through a batch.
34
- # : (untyped) -> untyped
35
- def validated_scope: (untyped) -> untyped
36
-
37
30
  # : () -> Array[untyped]
38
31
  def validated_records: () -> Array[untyped]
39
32
 
@@ -42,21 +35,21 @@ module PaperTrailDiff
42
35
  # The roots are preloaded first, because preparation reads their current
43
36
  # association state as a fallback and would otherwise walk it one root at a
44
37
  # time.
45
- # : (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped]) -> void
46
- def prepare: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped]) -> void
38
+ # : (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped], Hash[Array[String], TimeRange]) -> void
39
+ def prepare: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], untyped], Hash[Array[String], TimeRange]) -> void
47
40
 
48
41
  # : (Array[untyped], Hash[Array[String], RootVersionPlan]) -> bool
49
42
  def closes_live?: (Array[untyped], Hash[Array[String], RootVersionPlan]) -> bool
50
43
 
51
44
  # A plan closing on the live record reads history up to now; the others
52
45
  # stop at the window, so a past window does not load everything since.
53
- # : (Array[untyped], ?live: bool) -> Hash[Symbol, untyped]
54
- def preparation_range: (Array[untyped], ?live: bool) -> Hash[Symbol, untyped]
46
+ # : (Array[untyped], Hash[Array[String], TimeRange], live: bool) -> Hash[Symbol, untyped]
47
+ def preparation_range: (Array[untyped], Hash[Array[String], TimeRange], live: bool) -> Hash[Symbol, untyped]
55
48
 
56
49
  # A root with no versions in range has nothing to report, which is an empty
57
50
  # result rather than a failed request -- unless an activity view closes it
58
51
  # on current state, where its descendants may still have moved.
59
- # : (untyped, RootVersionPlan) -> Analysis
60
- def analysis_for: (untyped, RootVersionPlan) -> Analysis
52
+ # : (untyped, RootVersionPlan, TimeRange?) -> Analysis
53
+ def analysis_for: (untyped, RootVersionPlan, TimeRange?) -> Analysis
61
54
  end
62
55
  end
@@ -0,0 +1,23 @@
1
+ # Generated from lib/paper_trail_diff/approximate_paths.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # The requested paths prepared history cannot read exactly, each with why.
5
+ # PT-AT reads such a path instead, one record at a time, when the caller
6
+ # passes `allow_approximate: true`.
7
+ module ApproximatePaths
8
+ # : (AssociationTraversal, untyped) -> Array[[String, String]]
9
+ def self.call: (AssociationTraversal, untyped) -> Array[[ String, String ]]
10
+
11
+ # A has_many through reads its parts' conditions only, at any depth. A
12
+ # has_one through over a ranked part is refused whole, so its parts, too,
13
+ # are checked for conditions alone.
14
+ # : (untyped, ranked: bool) -> String?
15
+ def self.fallback_reason: (untyped, ranked: bool) -> String?
16
+
17
+ # A scope prepared history can read as conditions on stored attributes
18
+ # is batched like any other path. A polymorphic target's class, and so
19
+ # its scope, is known only per record.
20
+ # : (untyped, bool) -> String?
21
+ def self.reason_for: (untyped, bool) -> String?
22
+ end
23
+ end
@@ -49,6 +49,11 @@ module PaperTrailDiff
49
49
  # : (untyped, root: bool) -> Array[untyped]
50
50
  def supported_reflections: (untyped, root: bool) -> Array[untyped]
51
51
 
52
+ # Every request that reads history refuses a path whose target, or a
53
+ # model its has_many :through goes through, has no versions.
54
+ # : (untyped) -> bool
55
+ def unversioned?: (untyped) -> bool
56
+
52
57
  # : (untyped) -> untyped
53
58
  def reflection_target: (untyped) -> untyped
54
59
 
@@ -0,0 +1,29 @@
1
+ # Generated from lib/paper_trail_diff/association_key.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # PT-AT records which record a child pointed at by that record's id, and
5
+ # history matches children to owners and targets by id. An association
6
+ # keyed on another column (`primary_key:`) would read other records'
7
+ # history, so it is refused.
8
+ module AssociationKey
9
+ # Why the association, or a part of a through, cannot be read by id.
10
+ # : (untyped) -> String?
11
+ def self.unsupported_reason: (untyped) -> String?
12
+
13
+ # The reflection, or the first part of a through, keyed on a column other
14
+ # than its owner's or target's primary key.
15
+ # : (untyped) -> untyped
16
+ def self.keyed_part: (untyped) -> untyped
17
+
18
+ # A belongs_to names a key of its target; any other macro, one of its
19
+ # owner. A polymorphic target has no single primary key to compare with.
20
+ # : (untyped) -> bool
21
+ def self.other_key?: (untyped) -> bool
22
+
23
+ # Column names are strings once the key is, so the one mutation left,
24
+ # `eql?` for `==`, answers the same.
25
+ # mutant:disable
26
+ # : (untyped, untyped) -> bool
27
+ def self.same_column?: (untyped, untyped) -> bool
28
+ end
29
+ end
@@ -39,6 +39,10 @@ module PaperTrailDiff
39
39
  # : (untyped, untyped, root: bool) -> String?
40
40
  def self.unsupported_reason: (untyped, untyped, root: bool) -> String?
41
41
 
42
+ # History matches records by primary key, within one set of version tables.
43
+ # : (untyped) -> String?
44
+ def self.storage_reason: (untyped) -> String?
45
+
42
46
  # PT-AT records a HABTM's membership only when its owner saves a version,
43
47
  # in rows keyed by transaction and association name, not by owner. A root
44
48
  # checkpoint so holds the root's membership and no one else's: another
@@ -0,0 +1,29 @@
1
+ # Generated from lib/paper_trail_diff/batch_preload.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Which associations Active Record's preloader loads correctly for many
5
+ # owners at once.
6
+ module BatchPreload
7
+ # The preloader applies a limit or offset to all owners' records at once,
8
+ # not to each owner's, so such an association is loaded per record. A
9
+ # has_one is no exception. Through a part with a limit, an offset or a
10
+ # has_one cut, the preloader keeps what the part alone would load, while
11
+ # the through's own query keeps the part's conditions only.
12
+ #
13
+ # The declared scope is read, not a record's association scope: Active
14
+ # Record adds `limit(1)` to every has_one's, which would load every
15
+ # has_one per record.
16
+ # : (untyped) -> bool
17
+ def self.safe?: (untyped) -> bool
18
+
19
+ # : (untyped) -> untyped
20
+ def self.declared_relation: (untyped) -> untyped
21
+
22
+ # : (untyped) -> bool
23
+ def self.cut_part?: (untyped) -> bool
24
+
25
+ # Every part a through passes, at any depth.
26
+ # : (untyped) -> Array[untyped]
27
+ def self.through_parts: (untyped) -> Array[untyped]
28
+ end
29
+ end
@@ -4,11 +4,16 @@ module PaperTrailDiff
4
4
  # Builds one root's Analysis inside a batch, from versions the batch already
5
5
  # selected and history it already prepared.
6
6
  class BatchedRootAnalyzer
7
- # : (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool, ?within: untyped, ?snapshots: bool, ?group: Symbol?) -> void
8
- def initialize: (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool, ?within: untyped, ?snapshots: bool, ?group: Symbol?) -> void
7
+ # : (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool, view: ActivityView, ?within: untyped) -> void
8
+ def initialize: (tree: AssociationTree, timeline_snapshotter: untyped, activity_snapshotter: untyped, preparer: untyped, activity: bool, view: ActivityView, ?within: untyped) -> void
9
9
 
10
- # : (untyped, RootVersionPlan) -> Analysis
11
- def call: (untyped, RootVersionPlan) -> Analysis
10
+ # `window` is the root's window as the batch moved it to transaction edges.
11
+ # : (untyped, RootVersionPlan, ?TimeRange?) -> Analysis
12
+ def call: (untyped, RootVersionPlan, ?TimeRange?) -> Analysis
13
+
14
+ # The result for a root with nothing to read.
15
+ # : () -> Analysis
16
+ def empty: () -> Analysis
12
17
 
13
18
  private
14
19
 
@@ -16,19 +21,17 @@ module PaperTrailDiff
16
21
 
17
22
  @activity_snapshotter: untyped
18
23
 
19
- @group: Symbol?
20
-
21
24
  @preparer: untyped
22
25
 
23
- @snapshots: bool
24
-
25
26
  @timeline_snapshotter: untyped
26
27
 
27
28
  @tree: AssociationTree
28
29
 
30
+ @view: ActivityView
31
+
29
32
  @within: untyped
30
33
 
31
- # : (untyped, RootVersionPlan) -> Analysis
32
- def activity_analysis: (untyped, RootVersionPlan) -> Analysis
34
+ # : (untyped, RootVersionPlan, TimeRange?) -> Analysis
35
+ def activity_analysis: (untyped, RootVersionPlan, TimeRange?) -> Analysis
33
36
  end
34
37
  end
@@ -5,8 +5,8 @@ module PaperTrailDiff
5
5
  # queries. Only the range forms that mean the same thing for every root are
6
6
  # supported: a shared wall-clock window, or each root's own whole history.
7
7
  class BatchedRootVersions
8
- # : (Array[untyped], time_range: TimeRange?, version_scope: untyped, live_endpoints: Hash[Array[String], untyped]?, context_required: bool) -> void
9
- def initialize: (Array[untyped], time_range: TimeRange?, version_scope: untyped, live_endpoints: Hash[Array[String], untyped]?, context_required: bool) -> void
8
+ # : (Array[untyped], time_range: TimeRange?, version_scope: untyped, live_endpoints: Hash[Array[String], untyped]?, context_required: bool, windows: Hash[Array[String], TimeRange]) -> void
9
+ def initialize: (Array[untyped], time_range: TimeRange?, version_scope: untyped, live_endpoints: Hash[Array[String], untyped]?, context_required: bool, windows: Hash[Array[String], TimeRange]) -> void
10
10
 
11
11
  # Returns a plan per record identity.
12
12
  # : () -> Hash[Array[String], RootVersionPlan]
@@ -24,14 +24,24 @@ module PaperTrailDiff
24
24
 
25
25
  @version_scope: untyped
26
26
 
27
+ @windows: Hash[Array[String], TimeRange]
28
+
27
29
  # : (untyped, Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
28
30
  def select_model: (untyped, Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
29
31
 
32
+ # Moved windows only start and end earlier, so the versions read for the
33
+ # widest of them hold each root's own, and the first left past a moved end.
34
+ # : (Array[String], String, Hash[String, Array[untyped]], Hash[String, untyped]) -> [Array[untyped], untyped]
35
+ def own_window: (Array[String], String, Hash[String, Array[untyped]], Hash[String, untyped]) -> [ Array[untyped], untyped ]
36
+
30
37
  # : (untyped, Array[untyped]) -> [Hash[String, Array[untyped]], Set[untyped]?, Hash[String, untyped]]
31
38
  def model_versions: (untyped, Array[untyped]) -> [ Hash[String, Array[untyped]], Set[untyped]?, Hash[String, untyped] ]
32
39
 
33
- # : (Array[untyped], Set[untyped]?, untyped, untyped) -> RootVersionPlan
34
- def versions_for: (Array[untyped], Set[untyped]?, untyped, untyped) -> RootVersionPlan
40
+ # : (Array[untyped]) -> TimeRange?
41
+ def widest_range: (Array[untyped]) -> TimeRange?
42
+
43
+ # : (Array[untyped], untyped, Set[untyped]?, untyped) -> RootVersionPlan
44
+ def versions_for: (Array[untyped], untyped, Set[untyped]?, untyped) -> RootVersionPlan
35
45
 
36
46
  # The batch already loaded every root, so closing on current state reuses
37
47
  # that rather than reading each record again.
@@ -32,6 +32,12 @@ module PaperTrailDiff
32
32
 
33
33
  @tree: AssociationTree
34
34
 
35
+ # A root version's HABTM members include any created earlier in its
36
+ # transaction. A range ending at that version leaves those creations out
37
+ # as events, so the branch is read again there, whatever event led to it.
38
+ # : (untyped, untyped, Array[String]) -> Array[String]
39
+ def with_habtm: (untyped, untyped, Array[String]) -> Array[String]
40
+
35
41
  # : (Array[untyped], RecordSnapshot, Array[String], ActivityEvent?, bool) -> [bool, RecordSnapshot?]
36
42
  def incremental_event: (Array[untyped], RecordSnapshot, Array[String], ActivityEvent?, bool) -> [ bool, RecordSnapshot? ]
37
43
 
@@ -0,0 +1,86 @@
1
+ # Generated from lib/paper_trail_diff/change_row.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # One change from an activity step, flat enough for a history table or an
5
+ # export: a field that changed, or a record that appeared or disappeared,
6
+ # with the event the step attributes it to.
7
+ class ChangeRow
8
+ attr_reader change: Symbol
9
+
10
+ attr_reader association_path: Array[String]
11
+
12
+ attr_reader association_kind: Symbol?
13
+
14
+ # The record the row is about, or nil for the root itself.
15
+ attr_reader record: RecordReference?
16
+
17
+ # The field the row is about, or nil for a row about a whole record.
18
+ attr_reader attribute: String?
19
+
20
+ attr_reader from: untyped
21
+
22
+ attr_reader to: untyped
23
+
24
+ # The step's source boundary: for a transaction group, its first event.
25
+ attr_reader source: ActivityBoundary
26
+
27
+ # : (change: Symbol, association_path: Array[String], association_kind: Symbol?, record: RecordReference?, attribute: String?, from: untyped, to: untyped, source: ActivityBoundary) -> void
28
+ def initialize: (change: Symbol, association_path: Array[String], association_kind: Symbol?, record: RecordReference?, attribute: String?, from: untyped, to: untyped, source: ActivityBoundary) -> void
29
+
30
+ # The source's identifying fields sit beside the change rather than nested,
31
+ # so the hash is one row of a table as it stands.
32
+ # : () -> Hash[Symbol, untyped]
33
+ def to_h: () -> Hash[Symbol, untyped]
34
+
35
+ private
36
+
37
+ # : () -> Hash[Symbol, untyped]
38
+ def source_fields: () -> Hash[Symbol, untyped]
39
+ end
40
+
41
+ # Flattens one step's diff into change rows, in the diff's walking order.
42
+ #
43
+ # A row is about one record. An edited field is `:changed`. A record that
44
+ # appeared or disappeared is one `:added` or `:removed` row, followed by a
45
+ # row for each of its fields and for each record it holds, so a table can
46
+ # list a new comment's body without a second walker. That covers a record
47
+ # joining or leaving a collection, a to-one target set, cleared or replaced
48
+ # (the old target removed, then the new one added), and the root's own
49
+ # creation or deletion.
50
+ #
51
+ # Two kinds of entry add nothing a row would show. One that only groups
52
+ # others (an edited record, an association, a relationship) is left out,
53
+ # because the rows under it name the same record. A blank field of an added
54
+ # or removed record is left out too, because the record's own row already
55
+ # says it appeared or disappeared.
56
+ class ChangeRows
57
+ RECORD_ENTRIES: untyped
58
+
59
+ # : (Diff, source: ActivityBoundary) -> Array[ChangeRow]
60
+ def self.call: (Diff, source: ActivityBoundary) -> Array[ChangeRow]
61
+
62
+ # : (ActivityBoundary) -> void
63
+ def initialize: (ActivityBoundary) -> void
64
+
65
+ # : (Diff) -> Array[ChangeRow]
66
+ def call: (Diff) -> Array[ChangeRow]
67
+
68
+ private
69
+
70
+ @source: ActivityBoundary
71
+
72
+ # : (TraversalEntry) -> ChangeRow?
73
+ def row_for: (TraversalEntry) -> ChangeRow?
74
+
75
+ # : (TraversalEntry) -> ChangeRow
76
+ def changed_row: (TraversalEntry) -> ChangeRow
77
+
78
+ # An added record's state is the after side and a removed one's the before
79
+ # side, so a field's value goes on the side that has it.
80
+ # : (TraversalEntry, String?) -> ChangeRow
81
+ def presence_row: (TraversalEntry, String?) -> ChangeRow
82
+
83
+ # : (TraversalEntry, Symbol, String?, untyped, untyped) -> ChangeRow
84
+ def row: (TraversalEntry, Symbol, String?, untyped, untyped) -> ChangeRow
85
+ end
86
+ end
@@ -2,6 +2,8 @@
2
2
 
3
3
  module PaperTrailDiff
4
4
  # Compares collection snapshots with a low-allocation path for stable membership.
5
+ # Snapshots hold their records in type and ID order, so results follow it
6
+ # without sorting here.
5
7
  class CollectionComparator
6
8
  # : (AssociationSnapshot, AssociationSnapshot, record_comparer: untyped) -> void
7
9
  def initialize: (AssociationSnapshot, AssociationSnapshot, record_comparer: untyped) -> void
@@ -47,22 +49,6 @@ module PaperTrailDiff
47
49
  # : (Array[RecordSnapshot]) -> Hash[identity, RecordSnapshot]
48
50
  def index_records: (Array[RecordSnapshot]) -> Hash[identity, RecordSnapshot]
49
51
 
50
- # : (Array[identity]) -> Array[identity]
51
- def sorted_identities: (Array[identity]) -> Array[identity]
52
-
53
- # Identities sort by type first so that mixed id types stay comparable, then
54
- # naturally within one type. Ordering by the printed form instead would put
55
- # id 10 before id 2, which is deterministic but reads as unsorted wherever a
56
- # result is rendered.
57
- # : (identity) -> Array[untyped]
58
- def sortable_identity: (identity) -> Array[untyped]
59
-
60
- # Only the order of the group numbers matters, so moving the lowest one
61
- # down or the highest one up changes nothing; the spec checks the order.
62
- # mutant:disable
63
- # : (untyped) -> Array[untyped]
64
- def sortable_id: (untyped) -> Array[untyped]
65
-
66
52
  # : (identity) -> void
67
53
  def raise_duplicate_identity!: (identity) -> void
68
54
  end
@@ -5,18 +5,27 @@ module PaperTrailDiff
5
5
  class AssociationTree
6
6
  attr_reader children: Hash[String, AssociationTree]
7
7
 
8
+ # Takes what `includes` takes: a name, a dotted path, a hash of names to
9
+ # what to include below them, or an array of any of these.
8
10
  # : (untyped) -> AssociationTree
9
11
  def self.build: (untyped) -> AssociationTree
10
12
 
13
+ # : (untyped, String?) -> Array[String]
14
+ private def self.paths: (untyped, String?) -> Array[String]
15
+
16
+ # `{ comments: :replies }` names comments as well as their replies.
17
+ # : (untyped, untyped, String?) -> Array[String]
18
+ private def self.nested_paths: (untyped, untyped, String?) -> Array[String]
19
+
20
+ # : (String?, String | Symbol) -> String
21
+ private def self.joined: (String?, String | Symbol) -> String
22
+
11
23
  # : (Hash[String, untyped], String) -> void
12
24
  private def self.add_path: (Hash[String, untyped], String) -> void
13
25
 
14
26
  # : (Hash[String, untyped]) -> AssociationTree
15
27
  private def self.from_hash: (Hash[String, untyped]) -> AssociationTree
16
28
 
17
- # : (untyped) -> bool
18
- private def self.valid_values?: (untyped) -> bool
19
-
20
29
  # : (Hash[String, AssociationTree]) -> void
21
30
  def initialize: (Hash[String, AssociationTree]) -> void
22
31
 
@@ -63,5 +72,12 @@ module PaperTrailDiff
63
72
 
64
73
  # : (String) -> Array[String]
65
74
  def attributes_for: (String) -> Array[String]
75
+
76
+ # The names to leave out of what a version recorded. A root version is
77
+ # known to be the root's, so its own path's names apply; any other version
78
+ # does not say which path reached it, so only the names ignored everywhere
79
+ # do.
80
+ # : (root: bool) -> Array[String]
81
+ def recorded_attributes: (root: bool) -> Array[String]
66
82
  end
67
83
  end
@@ -13,6 +13,9 @@ module PaperTrailDiff
13
13
 
14
14
  private
15
15
 
16
+ # : (untyped, RootVersionPlan, TimeRange?) -> Analysis
17
+ def analysis_for: (untyped, RootVersionPlan, TimeRange?) -> Analysis
18
+
16
19
  # : (Hash[Array[String], Analysis]) -> Hash[Array[String], Analysis?]
17
20
  def with_unavailable: (Hash[Array[String], Analysis]) -> Hash[Array[String], Analysis?]
18
21
 
@@ -32,11 +35,11 @@ module PaperTrailDiff
32
35
 
33
36
  # A root destroyed before the window had no state inside it to read, so
34
37
  # only the others take the version after the window as context.
35
- # : (Array[untyped], Array[untyped]) -> Hash[Array[String], RootVersionPlan]
36
- def plans: (Array[untyped], Array[untyped]) -> Hash[Array[String], RootVersionPlan]
38
+ # : (Array[untyped], Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Array[String], RootVersionPlan]
39
+ def plans: (Array[untyped], Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Array[String], RootVersionPlan]
37
40
 
38
- # : (Array[untyped], bool) -> Hash[Array[String], RootVersionPlan]
39
- def plans_for: (Array[untyped], bool) -> Hash[Array[String], RootVersionPlan]
41
+ # : (Array[untyped], bool, Hash[Array[String], TimeRange]) -> Hash[Array[String], RootVersionPlan]
42
+ def plans_for: (Array[untyped], bool, Hash[Array[String], TimeRange]) -> Hash[Array[String], RootVersionPlan]
40
43
 
41
44
  # These records supply identity and model metadata only. Every reported
42
45
  # value comes from the batched historical plan; no per-root reify or live
@@ -47,10 +50,10 @@ module PaperTrailDiff
47
50
  # : () -> Array[untyped]
48
51
  def destroy_versions: () -> Array[untyped]
49
52
 
50
- # : (Array[untyped]) -> Hash[Symbol, untyped]
51
- def preparation_range: (Array[untyped]) -> Hash[Symbol, untyped]
53
+ # : (Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Symbol, untyped]
54
+ def preparation_range: (Array[untyped], Hash[Array[String], TimeRange]) -> Hash[Symbol, untyped]
52
55
 
53
- # : (Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
54
- def prepare: (Array[untyped], Hash[Array[String], RootVersionPlan]) -> void
56
+ # : (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], TimeRange]) -> void
57
+ def prepare: (Array[untyped], Hash[Array[String], RootVersionPlan], Hash[Array[String], TimeRange]) -> void
55
58
  end
56
59
  end
@@ -0,0 +1,56 @@
1
+ # Generated from lib/paper_trail_diff/deleted_root_filter.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Keeps the deleted roots the relation would have selected, by the state
5
+ # each held when it was destroyed. A relation's conditions read the live
6
+ # table, where a destroyed root has no row, so without this a report on one
7
+ # account's records would include every account's deletions.
8
+ class DeletedRootFilter
9
+ SLICE: ::Integer
10
+
11
+ # : (untyped) -> void
12
+ def initialize: (untyped) -> void
13
+
14
+ # nil when the relation's conditions cannot be read.
15
+ # : (untyped) -> DeletedRootFilter?
16
+ def self.readable: (untyped) -> DeletedRootFilter?
17
+
18
+ # A root whose destroy PaperTrail did not record has no state to test
19
+ # and stays, as it has no state to report either, unless the relation
20
+ # selects nothing. One whose destroy recorded no state is left out.
21
+ # : (Array[Array[String]]) -> Array[Array[String]]
22
+ def call: (Array[Array[String]]) -> Array[Array[String]]
23
+
24
+ private
25
+
26
+ @condition: ScopeCondition
27
+
28
+ @loader: DirectRecordStateLoader
29
+
30
+ @relation: untyped
31
+
32
+ # A relation delegates class methods to its model, so every mutation here,
33
+ # which drops `.model`, answers the same.
34
+ # mutant:disable
35
+ # : () -> untyped
36
+ def model: () -> untyped
37
+
38
+ # : (Hash[String, untyped]?) -> bool
39
+ def selected?: (Hash[String, untyped]?) -> bool
40
+
41
+ # The state each root held before its latest destroy, read in slices: a
42
+ # report lists every deleted root it reached, and SQL Server cannot plan an
43
+ # IN list of thousands.
44
+ # : (Array[String]) -> Hash[String, Hash[String, untyped]?]
45
+ def destroyed_states: (Array[String]) -> Hash[String, Hash[String, untyped]?]
46
+
47
+ # Read directly, with a column `skip:` left out of history as its default,
48
+ # so a report checks its ceiling before reifying anything. A version the
49
+ # direct reader declines, such as one naming a column since removed, is
50
+ # reified. Only the record's own attributes are read, so the association
51
+ # options, which only spare queries, cannot change an answer.
52
+ # mutant:disable
53
+ # : (untyped) -> Hash[String, untyped]?
54
+ def reified_attributes: (untyped) -> Hash[String, untyped]?
55
+ end
56
+ end
@@ -0,0 +1,35 @@
1
+ # Generated from lib/paper_trail_diff/deprecation.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Warns about options that do nothing any more and will be removed. In a
5
+ # Rails app, register the deprecator to configure it with the app's own:
6
+ #
7
+ # Rails.application.deprecators[:paper_trail_diff] = PaperTrailDiff.deprecator
8
+ module Deprecation
9
+ CLOSE_ON: ::String
10
+
11
+ ALLOW_EXPENSIVE: ::String
12
+
13
+ RELOAD_LIVE_ENDPOINTS: ::String
14
+
15
+ # Required when first used, as the library loads nothing it does not need.
16
+ # : () -> untyped
17
+ def self.deprecator: () -> untyped
18
+
19
+ # The one value close_on: took. It named what ends a wall-clock window,
20
+ # so it was meaningless without one, and until it is removed it is still
21
+ # checked as it was.
22
+ CLOSE_ON_CURRENT: ::Symbol
23
+
24
+ # : (Symbol?, untyped) -> void
25
+ def self.close_on!: (Symbol?, untyped) -> void
26
+
27
+ # : (untyped) -> void
28
+ def self.allow_expensive!: (untyped) -> void
29
+
30
+ # The value to use: the option still works until it is removed, and nil
31
+ # stands for its old default.
32
+ # : (untyped) -> untyped
33
+ def self.reload_live_endpoints!: (untyped) -> untyped
34
+ end
35
+ end