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,126 @@
1
+ # Generated from lib/paper_trail_diff/transaction_cut.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Moves each edge of a wall-clock window that falls inside one of a root's
5
+ # transactions back to where that transaction began, so the transaction is
6
+ # wholly in the later window.
7
+ #
8
+ # PT-AT reads a root's associations at the start of the transaction of the
9
+ # root version it reifies. A window starting just after a child saved its
10
+ # part of such a transaction therefore starts from the state before that
11
+ # child's change, and one ending there ends at it too, so the change belonged
12
+ # to no window and surfaced at the next transaction, under its author.
13
+ #
14
+ # Only the root's own versions on either side of an edge are consulted:
15
+ # rows locked by an update keep two transactions of one root from
16
+ # interleaving, so a transaction holding a root version and crossing the edge
17
+ # holds the root's nearest version on one side of it. Each edge is moved from
18
+ # where it was asked for, never from where another edge moved, so adjacent
19
+ # windows move their shared edge alike.
20
+ module TransactionCut
21
+ # One edge of a window. A strict edge keeps versions recorded at its
22
+ # instant on the left, as an inclusive end does. A plain class rather than
23
+ # Data.define, which arrived in Ruby 3.2 while this gem supports 3.1.
24
+ class Edge
25
+ # : (Time, bool) -> void
26
+ def initialize: (Time, bool) -> void
27
+
28
+ # : (untyped) -> untyped
29
+ def left: (untyped) -> untyped
30
+
31
+ # : (untyped) -> untyped
32
+ def right: (untyped) -> untyped
33
+
34
+ @strict: bool
35
+
36
+ @time: Time
37
+ end
38
+
39
+ # Roots, or transactions, per statement. SQL Server compiles every
40
+ # statement afresh, since its ids are written into it, in time that grows
41
+ # with their number; fewer statements than this cost more than they save.
42
+ SLICE: ::Integer
43
+
44
+ # The same as `windows` for a batch of roots, keyed by identity.
45
+ # : (Array[untyped], TimeRange?) -> Hash[Array[String], TimeRange]
46
+ def self.batch_windows: (Array[untyped], TimeRange?) -> Hash[Array[String], TimeRange]
47
+
48
+ # Where history for a batch must be read from: the earliest moved start.
49
+ # : (TimeRange?, Hash[Array[String], TimeRange]) -> Time?
50
+ def self.earliest_start: (TimeRange?, Hash[Array[String], TimeRange]) -> Time?
51
+
52
+ # The windows that move, keyed by root id. A root missing from the result
53
+ # keeps the window as asked.
54
+ # : (untyped, Array[untyped], TimeRange) -> Hash[String, TimeRange]
55
+ def self.windows: (untyped, Array[untyped], TimeRange) -> Hash[String, TimeRange]
56
+
57
+ # A transaction holds its rows only while it runs, so in history as an
58
+ # application saves it an edge moves by moments. A longer move means a
59
+ # long transaction or rewritten times, which only the application can
60
+ # judge, so each move is reported rather than logged or refused.
61
+ # : (untyped, String, TimeRange, Time?, Time?) -> TimeRange
62
+ def self.moved_window: (untyped, String, TimeRange, Time?, Time?) -> TimeRange
63
+
64
+ # : (untyped) -> untyped
65
+ def self.transaction_versions: (untyped) -> untyped
66
+
67
+ # Each root's earliest start among its transactions that cross the edge.
68
+ # : (untyped, Array[untyped], Edge) -> Hash[String, Time]
69
+ def self.moved_edges: (untyped, Array[untyped], Edge) -> Hash[String, Time]
70
+
71
+ # The roots whose versions next to the edge each transaction holds.
72
+ # : (untyped, Array[untyped], Edge) -> Hash[untyped, Array[String]]
73
+ def self.nearest_roots: (untyped, Array[untyped], Edge) -> Hash[untyped, Array[String]]
74
+
75
+ # Each root's nearest versions on either side of an edge, as [id,
76
+ # transaction] pairs; versions tied at the nearest instant are all kept.
77
+ # One statement per slice: a grouped pass over the roots' versions finds
78
+ # both instants, and a join reads the versions saved at either. A lookup
79
+ # per root, joined by UNION ALL, took SQL Server about a second per 200
80
+ # roots to compile. Rows read without a model come back as the adapter
81
+ # returns them, so the transaction is cast as the grouped query's keys are.
82
+ # : (untyped, Array[untyped], Edge) -> Array[[String, untyped]]
83
+ def self.nearest: (untyped, Array[untyped], Edge) -> Array[[ String, untyped ]]
84
+
85
+ # The roots' versions saved in a transaction at either nearest instant.
86
+ # : (untyped, Array[untyped], Edge) -> String
87
+ def self.nearest_sql: (untyped, Array[untyped], Edge) -> String
88
+
89
+ # Each root's latest instant before the edge and earliest after it, from
90
+ # every version, saved in a transaction or not.
91
+ # : (untyped, Edge) -> untyped
92
+ def self.nearest_instants: (untyped, Edge) -> untyped
93
+
94
+ # The latest or earliest of the times on one side of the edge.
95
+ # : (untyped, untyped, untyped) -> untyped
96
+ def self.side_instant: (untyped, untyped, untyped) -> untyped
97
+
98
+ # The same root's versions saved at either of its instants.
99
+ # : (untyped, untyped) -> untyped
100
+ def self.at_either: (untyped, untyped) -> untyped
101
+
102
+ # Where each transaction that has versions on both sides of the edge began.
103
+ # : (untyped, Array[untyped], Edge) -> Hash[untyped, Time]
104
+ def self.crossing_starts: (untyped, Array[untyped], Edge) -> Hash[untyped, Time]
105
+
106
+ # Another version of the same transaction on the edge's later side.
107
+ # : (untyped, Edge) -> untyped
108
+ def self.later_version: (untyped, Edge) -> untyped
109
+
110
+ # The version table under a second name, for a subquery over it. Any name
111
+ # serves, and SQLite even accepts an empty one other databases refuse, so
112
+ # no spec can tell the mutations apart.
113
+ # mutant:disable
114
+ # : (untyped) -> untyped
115
+ def self.other_versions: (untyped) -> untyped
116
+
117
+ # Arel ships no signatures; see VersionQuery. Any spelling of the constant
118
+ # finds the same module.
119
+ # mutant:disable
120
+ # : () -> untyped
121
+ def self.arel: () -> untyped
122
+
123
+ # : (TimeRange, Time?, Time?) -> TimeRange
124
+ def self.moved: (TimeRange, Time?, Time?) -> TimeRange
125
+ end
126
+ end
@@ -3,30 +3,88 @@
3
3
  module PaperTrailDiff
4
4
  # Checks that a model can be traversed before any reconstruction starts, and
5
5
  # that association tracking is actually available when history is involved.
6
+ # `diagnose` reports the same refusals instead of raising the first.
6
7
  class TraversalPreparer
7
- # : (tree: AssociationTree, traversal: AssociationTraversal) -> void
8
- def initialize: (tree: AssociationTree, traversal: AssociationTraversal) -> void
8
+ # One reason to refuse a request: the error `call` raises, and the code
9
+ # and path `diagnose` reports.
10
+ class Refusal
11
+ attr_reader error: untyped
12
+
13
+ attr_reader code: Symbol
14
+
15
+ attr_reader message: String
16
+
17
+ attr_reader path: String?
18
+
19
+ # : (untyped, Symbol, String, ?String?) -> void
20
+ def initialize: (untyped, Symbol, String, ?String?) -> void
21
+ end
22
+
23
+ PROBLEMS: untyped
24
+
25
+ # Each model a path's history needs versions of and has none, with the
26
+ # refusal's code: the target, then each model a has_many :through goes
27
+ # through. A polymorphic target is not known until a row names it;
28
+ # `diagnose` reports that separately rather than guessing here.
29
+ # : (untyped) -> Array[[Symbol, untyped]]
30
+ def self.unversioned_models: (untyped) -> Array[[ Symbol, untyped ]]
31
+
32
+ # A has_many :through reads past membership from the versions of the
33
+ # models it goes through, so each of them needs history too.
34
+ # : (untyped) -> Array[untyped]
35
+ def self.through_models: (untyped) -> Array[untyped]
36
+
37
+ # : (tree: AssociationTree, traversal: AssociationTraversal, ?allow_approximate: bool) -> void
38
+ def initialize: (tree: AssociationTree, traversal: AssociationTraversal, ?allow_approximate: bool) -> void
9
39
 
10
40
  # : (untyped, historical: bool) -> void
11
41
  def call: (untyped, historical: bool) -> void
12
42
 
43
+ # Every reason to refuse a request over the model, in the order `call`
44
+ # raises them. Live-to-live comparison reads current state, so only the
45
+ # traversal itself is checked for it.
46
+ # : (untyped, historical: bool) -> Array[Refusal]
47
+ def refusals: (untyped, historical: bool) -> Array[Refusal]
48
+
13
49
  private
14
50
 
51
+ @allow_approximate: bool
52
+
53
+ @refusals: Hash[Array[untyped], Array[Refusal]]
54
+
15
55
  @traversal: AssociationTraversal
16
56
 
17
57
  @tree: AssociationTree
18
58
 
59
+ # : (untyped, bool) -> Array[Refusal]
60
+ def collect: (untyped, bool) -> Array[Refusal]
61
+
62
+ # : (untyped) -> Refusal?
63
+ def traversal_refusal: (untyped) -> Refusal?
64
+
65
+ # A path prepared history cannot read is read with PT-AT, which rebuilds
66
+ # an association from its current members, swapping in older versions of
67
+ # them. A record that entered the association since, such as one moved
68
+ # into a scope or restored from a soft delete, then reads as a member it
69
+ # was not, and one that left reads as missing. Only a caller who accepts
70
+ # that may read such a path.
71
+ # : (untyped) -> Array[Refusal]
72
+ def approximate_refusals: (untyped) -> Array[Refusal]
73
+
19
74
  # A model PaperTrail never versioned has no history to reconstruct, so a
20
75
  # comparison over it can only ever answer "nothing changed" -- which is a
21
76
  # wrong answer rather than an empty one. Live-to-live comparison reads
22
77
  # current state and is unaffected, so this applies to historical work only.
23
- # : (untyped) -> void
24
- def ensure_versioned_targets!: (untyped) -> void
78
+ # : (untyped) -> Array[Refusal]
79
+ def unversioned_refusals: (untyped) -> Array[Refusal]
80
+
81
+ # : (String, untyped, Symbol) -> Refusal
82
+ def unversioned: (String, untyped, Symbol) -> Refusal
25
83
 
26
- # : (untyped) -> bool
27
- def versioned?: (untyped) -> bool
84
+ # : () -> bool
85
+ def association_tracking?: () -> bool
28
86
 
29
- # : () -> void
30
- def ensure_association_tracking!: () -> void
87
+ # : () -> Refusal
88
+ def tracking_refusal: () -> Refusal
31
89
  end
32
90
  end
@@ -11,13 +11,32 @@ module PaperTrailDiff
11
11
  # : (untyped, untyped) -> bool
12
12
  def self?.at_or_after?: (untyped, untyped) -> bool
13
13
 
14
+ # A range starting at a version starts before that version's transaction,
15
+ # as PT-AT reads associations there. A version saved earlier in the same
16
+ # transaction, such as the child update behind a `touch: true` parent
17
+ # version, can be recorded before the start, so the start moves back to
18
+ # the earliest version of each root's first transaction in the range.
19
+ # History loaded from the start alone would read that child after its
20
+ # change.
21
+ # : (Array[untyped], untyped) -> untyped
22
+ def self?.transaction_start: (Array[untyped], untyped) -> untyped
23
+
24
+ # The transaction of each root's first version at or after the start.
25
+ # : (Array[untyped], untyped) -> Array[untyped]
26
+ def self?.opening_transactions: (Array[untyped], untyped) -> Array[untyped]
27
+
28
+ # A custom version class need not carry the column, and PaperTrail leaves
29
+ # it nil outside a transaction. Both read as "no transaction here", which
30
+ # groups with nothing.
31
+ # : (untyped) -> untyped
32
+ def self?.transaction_id: (untyped) -> untyped
33
+
14
34
  # : (untyped) -> bool
15
35
  def self?.version_record?: (untyped) -> bool
16
36
 
37
+ # The same row of the same version table. A record or instant is never a
38
+ # version.
17
39
  # : (untyped, untyped) -> bool
18
40
  def self?.same_version?: (untyped, untyped) -> bool
19
-
20
- # : (untyped, untyped) -> bool
21
- def self?.orderable_tie?: (untyped, untyped) -> bool
22
41
  end
23
42
  end
@@ -9,13 +9,29 @@ module PaperTrailDiff
9
9
  # : (untyped) -> untyped
10
10
  def self?.chronological: (untyped) -> untyped
11
11
 
12
+ # Every version of a model's items. They are read from the version class
13
+ # rather than through the model's versions association, whose scope may
14
+ # leave some out: a history replayed without them credits their changes to
15
+ # the next version kept.
16
+ # : (untyped) -> untyped
17
+ def self?.for_model: (untyped) -> untyped
18
+
19
+ # The versions of the given items, read the same way.
20
+ # : (untyped, untyped) -> untyped
21
+ def self?.for_items: (untyped, untyped) -> untyped
22
+
12
23
  # Keeps each item's earliest version among those the block also accepts:
13
24
  # no other version of the same item that the block accepts is earlier. A
14
25
  # correlated NOT EXISTS stays portable where window functions are not.
15
26
  # : (untyped) ?{ (untyped) -> untyped } -> untyped
16
27
  def self?.no_earlier_version: (untyped) ?{ (untyped) -> untyped } -> untyped
17
28
 
18
- # : (untyped, untyped) ?{ (untyped) -> untyped } -> untyped
19
- def self?.earlier_version: (untyped, untyped) ?{ (untyped) -> untyped } -> untyped
29
+ # The same for either side of an instant: each item's earliest version
30
+ # when the versions lie after it, and its latest when they lie before.
31
+ # : (untyped, later: bool) ?{ (untyped) -> untyped } -> untyped
32
+ def self?.no_nearer_version: (untyped, later: bool) ?{ (untyped) -> untyped } -> untyped
33
+
34
+ # : (untyped, untyped, later: bool) ?{ (untyped) -> untyped } -> untyped
35
+ def self?.nearer_version: (untyped, untyped, later: bool) ?{ (untyped) -> untyped } -> untyped
20
36
  end
21
37
  end
@@ -6,6 +6,10 @@ module PaperTrailDiff
6
6
  # caller, because the one that reveals the last selected mutation is drawn
7
7
  # from them.
8
8
  class VersionScopeFilter
9
+ # A filter is a callable that narrows the version relation.
10
+ # : (untyped) -> untyped
11
+ def self.validated: (untyped) -> untyped
12
+
9
13
  # : (untyped) -> void
10
14
  def initialize: (untyped) -> void
11
15
 
@@ -16,11 +20,6 @@ module PaperTrailDiff
16
20
  # : (untyped) -> Set[untyped]?
17
21
  def chosen_ids: (untyped) -> Set[untyped]?
18
22
 
19
- private
20
-
21
23
  @scope: untyped
22
-
23
- # : (untyped) -> untyped
24
- def validated: (untyped) -> untyped
25
24
  end
26
25
  end
@@ -3,17 +3,20 @@
3
3
  module PaperTrailDiff
4
4
  # Checks the recorded sequence itself, before any question of association
5
5
  # setup: whether the versions can be ordered at all, and whether timestamps
6
- # they share hide changes that ordering alone cannot recover.
6
+ # they share hide changes from a path PT-AT reads.
7
7
  class VersionSequenceDiagnostics
8
- # : (untyped, untyped, ?associations_selected: bool) -> void
9
- def initialize: (untyped, untyped, ?associations_selected: bool) -> void
8
+ # : (untyped, untyped, ?fallback_selected: bool) -> void
9
+ def initialize: (untyped, untyped, ?fallback_selected: bool) -> void
10
10
 
11
+ # The read runs in a savepoint, so that a query that fails here leaves a
12
+ # snapshot transaction around it usable: PostgreSQL refuses every later
13
+ # statement of a transaction once one has failed.
11
14
  # : () -> Array[DiagnosticIssue]
12
15
  def call: () -> Array[DiagnosticIssue]
13
16
 
14
17
  private
15
18
 
16
- @associations_selected: bool
19
+ @fallback_selected: bool
17
20
 
18
21
  @from_version: untyped
19
22
 
@@ -25,15 +28,22 @@ module PaperTrailDiff
25
28
  # : (Array[untyped]) -> DiagnosticIssue?
26
29
  def unorderable: (Array[untyped]) -> DiagnosticIssue?
27
30
 
28
- # Association membership is recorded per version but resolved by timestamp,
29
- # so a tie hides any association change across that pair. Unlike an
30
- # unorderable sequence this is not always wrong: if nothing associated
31
- # changed between them the result is correct, and the gem cannot tell which
32
- # it is, because not seeing the change is the symptom. So it warns.
31
+ # Loaded history orders versions that share a timestamp by id, but PT-AT
32
+ # places association changes by timestamp alone, so a path it reads loses
33
+ # any change between such a pair. Unlike an unorderable sequence this is
34
+ # not always wrong: if nothing that path reaches changed between them the
35
+ # result is correct, and the gem cannot tell which it is, because not
36
+ # seeing the change is the symptom. So it warns.
33
37
  # : (Array[untyped]) -> DiagnosticIssue?
34
38
  def tied_timestamps: (Array[untyped]) -> DiagnosticIssue?
35
39
 
36
40
  # : () -> Array[untyped]
37
41
  def ordered_range_versions: () -> Array[untyped]
42
+
43
+ # Between the two versions, in either order, or from the one version on
44
+ # when the other endpoint is the current record. A version that recorded
45
+ # no time bounds nothing.
46
+ # : () -> Range[untyped]?
47
+ def time_range: () -> Range[untyped]?
38
48
  end
39
49
  end
@@ -0,0 +1,30 @@
1
+ # Generated from lib/paper_trail_diff/version_table.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # PT-AT reads an association's history from its owner's version tables: it
5
+ # looks for a child's versions in the owner's version table, and numbers a
6
+ # transaction by the first version saved in it, in whichever table. A model
7
+ # whose versions, or version associations, live in another table than its
8
+ # owner's would read other records' versions or none, so it is refused.
9
+ module VersionTable
10
+ # Why the association, or a part of a through, cannot be read across
11
+ # version tables.
12
+ # : (untyped) -> String?
13
+ def self.unsupported_reason: (untyped) -> String?
14
+
15
+ # The reflection, or the first part of a through, whose ends keep versions
16
+ # in different tables. A polymorphic belongs_to names no single target,
17
+ # and an unversioned target has no history to compare.
18
+ # : (untyped) -> untyped
19
+ def self.separate_part: (untyped) -> untyped
20
+
21
+ # PT-AT's version association rows joined to the versions they were saved
22
+ # with. Its `belongs_to :version` names PaperTrail's default class whatever
23
+ # table a model's versions are in, so the join names the table instead.
24
+ # : (untyped, untyped) -> untyped
25
+ def self.joined: (untyped, untyped) -> untyped
26
+
27
+ # : (untyped) -> String
28
+ def self.tables: (untyped) -> String
29
+ end
30
+ end
@@ -9,36 +9,33 @@ module PaperTrailDiff
9
9
  SUPPORTED_ASSOCIATION_MACROS: untyped
10
10
 
11
11
  # Compares net state between explicit PaperTrail-version or current-record endpoints.
12
- # : (untyped, untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> Diff
13
- def self.compare: (untyped, untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> Diff
12
+ # : (untyped, untyped, ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?allow_approximate: bool) -> Diff
13
+ def self.compare: (untyped, untyped, ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?allow_approximate: bool) -> Diff
14
14
 
15
15
  # Compares many independent endpoint pairs while batching current-record loading.
16
- # : (Array[comparison_input], ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?allow_expensive: bool) -> comparison_results
17
- def self.compare_many: (Array[comparison_input], ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?allow_expensive: bool) -> comparison_results
16
+ # : (Array[comparison_input], ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?allow_expensive: bool?, ?allow_approximate: bool) -> comparison_results
17
+ def self.compare_many: (Array[comparison_input], ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?allow_expensive: bool?, ?allow_approximate: bool) -> comparison_results
18
18
 
19
19
  # Compares every adjacent reconstructed state in an inclusive version range,
20
20
  # by default the record's whole history through its current state.
21
- # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?version_scope: untyped, ?close_on: Symbol?) -> Array[Step]
22
- def self.timeline: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?version_scope: untyped, ?close_on: Symbol?) -> Array[Step]
21
+ # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?close_on: Symbol?, ?allow_approximate: bool) -> Array[Step]
22
+ def self.timeline: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?close_on: Symbol?, ?allow_approximate: bool) -> Array[Step]
23
23
 
24
24
  # Compares adjacent root and selected-descendant activity boundaries.
25
- # `reload_live_endpoints:` applies whenever the range ends at the current
26
- # record: an explicit `to:` record, the default range, or a window with no
27
- # later version.
28
- # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
29
- def self.activity_timeline: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
25
+ # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Array[ActivityStep]
26
+ def self.activity_timeline: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Array[ActivityStep]
30
27
 
31
28
  # Builds an endpoint diff and root-checkpoint timeline while normalizing each version once.
32
- # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Analysis
33
- def self.analyze: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Analysis
29
+ # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Analysis
30
+ def self.analyze: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Analysis
34
31
 
35
32
  # Analyzes an array of records over one shared range, preparing their
36
33
  # selected history once for the batch instead of once per record, and
37
34
  # returns a frozen Hash keyed by identity. Roots with nothing to report in
38
35
  # the window return an empty `Analysis`. To let a relation choose the
39
36
  # records, use `analyze_scope`.
40
- # : (Array[untyped], ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?allow_expensive: bool) -> Hash[identity, Analysis]
41
- def self.analyze_many: (Array[untyped], ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?allow_expensive: bool) -> Hash[identity, Analysis]
37
+ # : (Array[untyped], ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> Hash[identity, Analysis]
38
+ def self.analyze_many: (Array[untyped], ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> Hash[identity, Analysis]
42
39
 
43
40
  # Analyzes every root the relation reaches whose history moved inside the
44
41
  # window. With `activity: true`, a change to a record on one of the
@@ -66,15 +63,19 @@ module PaperTrailDiff
66
63
  # Note also that a relation selects on current state, not on state during
67
64
  # the window: `where(status: 'published')` means published *now*, which is a
68
65
  # different set from what was published while the window was open.
69
- # : (untyped, limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool, ?allow_expensive: bool) -> ScopedAnalysis
70
- def self.analyze_scope: (untyped, limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool, ?allow_expensive: bool) -> ScopedAnalysis
66
+ # : (untyped, limit: Integer?, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
67
+ def self.analyze_scope: (untyped, limit: Integer?, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
71
68
 
72
69
  # Recent root and selected-child activity through the current saved state,
73
70
  # for every root that changed or whose requested associations did.
74
71
  # Historical windows remain explicit on analyze_scope; this entry point is
75
72
  # deliberately named for a report through now rather than an as-of query.
76
- # : (untyped, since: untyped, limit: Integer, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?allow_expensive: bool) -> ScopedAnalysis
77
- def self.report: (untyped, since: untyped, limit: Integer, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?allow_expensive: bool) -> ScopedAnalysis
73
+ # : (untyped, since: untyped, limit: Integer, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
74
+ def self.report: (untyped, since: untyped, limit: Integer, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
75
+
76
+ # Warns about deprecated options; see Deprecation.
77
+ # : () -> untyped
78
+ def self.deprecator: () -> untyped
78
79
 
79
80
  # Returns the association macros this release can normalize.
80
81
  # : () -> Array[Symbol]
@@ -84,9 +85,11 @@ module PaperTrailDiff
84
85
  # : (untyped, ?max_depth: Integer) -> Array[AssociationDescriptor]
85
86
  def self.association_paths: (untyped, ?max_depth: Integer) -> Array[AssociationDescriptor]
86
87
 
87
- # Reports known reconstruction hazards without mutating application state.
88
- # : (untyped, untyped, ?associations: Array[String | Symbol]) -> DiagnosticReport
89
- def self.diagnose: (untyped, untyped, ?associations: Array[String | Symbol]) -> DiagnosticReport
88
+ # Reports known reconstruction hazards without mutating application state,
89
+ # for the endpoints `compare` takes: two versions, or a version and the
90
+ # current record. Every reason `compare` would refuse them is an error.
91
+ # : (untyped, untyped, ?associations: association_option, ?allow_approximate: bool) -> DiagnosticReport
92
+ def self.diagnose: (untyped, untyped, ?associations: association_option, ?allow_approximate: bool) -> DiagnosticReport
90
93
 
91
94
  # Looks inside an attribute the database stores whole, such as a JSON or
92
95
  # jsonb column, and reports which keys changed.
@@ -111,9 +114,7 @@ module PaperTrailDiff
111
114
 
112
115
  # Reads what PaperTrail recorded with one version: its `object_changes`,
113
116
  # typed by the version's model, as `{ "title" => <from "Draft" to "Published"> }`.
114
- #
115
- # versions = PaperTrail::Version.where(id: steps.map { _1.source_boundary.version_id })
116
- # versions.to_h { [_1.id, PaperTrailDiff.recorded_changes(_1)] }
117
+ # Activity methods read it for every step source with `recorded_changes: true`.
117
118
  #
118
119
  # A step's diff compares the states before and after an event, so it also
119
120
  # includes anything saved without a version in between; this does not.
@@ -149,10 +150,12 @@ module PaperTrailDiff
149
150
 
150
151
  type comparison_results = Hash[identity, Diff]
151
152
 
152
- type report_options = { within: untyped, activity: bool, version_scope: untyped, close_on: Symbol?, snapshots: bool, group: Symbol? }
153
+ type report_options = { within: untyped, activity: bool, version_scope: untyped, view: ActivityView }
153
154
 
154
155
  type ignore_option = Array[String | Symbol] | Hash[String | Symbol, untyped]
155
156
 
157
+ type association_option = String | Symbol | Array[untyped] | Hash[untyped, untyped]
158
+
156
159
  type reference_key = :type | :id | "type" | "id"
157
160
 
158
161
  type traversal_context = :change | :included_state