paper_trail_diff 0.13.1 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (181) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +630 -0
  3. data/QUICKSTART.md +30 -10
  4. data/README.md +91 -13
  5. data/docs/architecture.md +62 -18
  6. data/docs/performance.md +116 -298
  7. data/docs/reference.md +554 -102
  8. data/docs/testing.md +93 -14
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +19 -9
  10. data/lib/paper_trail_diff/activity_boundary.rb +83 -26
  11. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
  12. data/lib/paper_trail_diff/activity_collection_event_applier.rb +11 -1
  13. data/lib/paper_trail_diff/activity_collection_record_updater.rb +16 -2
  14. data/lib/paper_trail_diff/activity_event.rb +41 -10
  15. data/lib/paper_trail_diff/activity_event_record_resolver.rb +20 -1
  16. data/lib/paper_trail_diff/activity_event_route_finder.rb +2 -1
  17. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +1 -1
  18. data/lib/paper_trail_diff/activity_history.rb +34 -9
  19. data/lib/paper_trail_diff/activity_range.rb +32 -5
  20. data/lib/paper_trail_diff/activity_relationship.rb +12 -0
  21. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +5 -2
  22. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
  23. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +131 -0
  24. data/lib/paper_trail_diff/activity_timeline_builder.rb +281 -120
  25. data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
  26. data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
  27. data/lib/paper_trail_diff/activity_version_collector.rb +37 -24
  28. data/lib/paper_trail_diff/activity_view.rb +69 -0
  29. data/lib/paper_trail_diff/analysis.rb +13 -1
  30. data/lib/paper_trail_diff/analysis_batch.rb +24 -30
  31. data/lib/paper_trail_diff/approximate_paths.rb +48 -0
  32. data/lib/paper_trail_diff/association_activity_edge.rb +236 -0
  33. data/lib/paper_trail_diff/association_activity_selection.rb +197 -0
  34. data/lib/paper_trail_diff/association_discovery.rb +14 -11
  35. data/lib/paper_trail_diff/association_key.rb +56 -0
  36. data/lib/paper_trail_diff/association_traversal.rb +180 -47
  37. data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
  38. data/lib/paper_trail_diff/batch_preload.rb +53 -0
  39. data/lib/paper_trail_diff/batched_root_analyzer.rb +12 -14
  40. data/lib/paper_trail_diff/batched_root_versions.rb +53 -47
  41. data/lib/paper_trail_diff/change_row.rb +133 -0
  42. data/lib/paper_trail_diff/collection_comparator.rb +5 -32
  43. data/lib/paper_trail_diff/comparison_batch.rb +37 -10
  44. data/lib/paper_trail_diff/configuration.rb +35 -12
  45. data/lib/paper_trail_diff/deleted_analysis_batch.rb +45 -27
  46. data/lib/paper_trail_diff/deleted_root_filter.rb +79 -0
  47. data/lib/paper_trail_diff/deprecation.rb +61 -0
  48. data/lib/paper_trail_diff/diagnostics.rb +105 -102
  49. data/lib/paper_trail_diff/direct_record_state_loader.rb +10 -1
  50. data/lib/paper_trail_diff/endpoint.rb +26 -3
  51. data/lib/paper_trail_diff/errors.rb +5 -2
  52. data/lib/paper_trail_diff/fallback_paths.rb +38 -0
  53. data/lib/paper_trail_diff/habtm_transaction_owners.rb +68 -0
  54. data/lib/paper_trail_diff/historical_association_reifier.rb +34 -6
  55. data/lib/paper_trail_diff/historical_filter.rb +19 -10
  56. data/lib/paper_trail_diff/historical_snapshot_store.rb +63 -76
  57. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +12 -13
  58. data/lib/paper_trail_diff/live_graph_collector.rb +1 -1
  59. data/lib/paper_trail_diff/nested_comparator.rb +19 -18
  60. data/lib/paper_trail_diff/paper_trail_adapter.rb +136 -125
  61. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +14 -2
  62. data/lib/paper_trail_diff/prepared_activity_index.rb +110 -36
  63. data/lib/paper_trail_diff/prepared_edge_loader.rb +31 -46
  64. data/lib/paper_trail_diff/prepared_history.rb +70 -53
  65. data/lib/paper_trail_diff/prepared_history_loader.rb +34 -43
  66. data/lib/paper_trail_diff/prepared_record_index.rb +64 -7
  67. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +1 -1
  68. data/lib/paper_trail_diff/prepared_state_association_reader.rb +119 -29
  69. data/lib/paper_trail_diff/recorded_changes.rb +83 -0
  70. data/lib/paper_trail_diff/recorded_class.rb +53 -0
  71. data/lib/paper_trail_diff/root_version_selection.rb +4 -2
  72. data/lib/paper_trail_diff/scope_condition.rb +386 -0
  73. data/lib/paper_trail_diff/scope_ranking.rb +206 -0
  74. data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
  75. data/lib/paper_trail_diff/scoped_analysis_builder.rb +20 -11
  76. data/lib/paper_trail_diff/scoped_root_selection.rb +105 -49
  77. data/lib/paper_trail_diff/snapshot.rb +16 -1
  78. data/lib/paper_trail_diff/snapshot_normalizer.rb +10 -3
  79. data/lib/paper_trail_diff/support.rb +38 -6
  80. data/lib/paper_trail_diff/time_range.rb +37 -18
  81. data/lib/paper_trail_diff/time_version_range.rb +5 -5
  82. data/lib/paper_trail_diff/timeline_builder.rb +7 -7
  83. data/lib/paper_trail_diff/timeline_range.rb +9 -1
  84. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
  85. data/lib/paper_trail_diff/transaction_cut.rb +181 -0
  86. data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
  87. data/lib/paper_trail_diff/version.rb +1 -1
  88. data/lib/paper_trail_diff/version_association_candidate_scope.rb +13 -3
  89. data/lib/paper_trail_diff/version_boundary.rb +37 -8
  90. data/lib/paper_trail_diff/version_query.rb +34 -10
  91. data/lib/paper_trail_diff/version_range.rb +8 -15
  92. data/lib/paper_trail_diff/version_scope_filter.rb +20 -13
  93. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +31 -16
  94. data/lib/paper_trail_diff/version_table.rb +60 -0
  95. data/lib/paper_trail_diff.rb +126 -55
  96. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +10 -2
  97. data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
  98. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +5 -0
  99. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +5 -0
  100. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
  101. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +7 -0
  102. data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
  103. data/sig/generated/paper_trail_diff/activity_range.rbs +14 -3
  104. data/sig/generated/paper_trail_diff/activity_relationship.rbs +3 -0
  105. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +2 -0
  106. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
  107. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +79 -0
  108. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -28
  109. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
  110. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +12 -4
  111. data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
  112. data/sig/generated/paper_trail_diff/analysis.rbs +8 -1
  113. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
  114. data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
  115. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +148 -0
  116. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +112 -0
  117. data/sig/generated/paper_trail_diff/association_discovery.rbs +8 -5
  118. data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
  119. data/sig/generated/paper_trail_diff/association_traversal.rbs +88 -9
  120. data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
  121. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -10
  122. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -10
  123. data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
  124. data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
  125. data/sig/generated/paper_trail_diff/comparison_batch.rbs +22 -4
  126. data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
  127. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +20 -8
  128. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +48 -0
  129. data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
  130. data/sig/generated/paper_trail_diff/diagnostics.rbs +44 -32
  131. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +6 -0
  132. data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
  133. data/sig/generated/paper_trail_diff/errors.rbs +5 -2
  134. data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
  135. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +40 -0
  136. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +13 -0
  137. data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
  138. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +36 -30
  139. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +5 -3
  140. data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
  141. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +55 -48
  142. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
  143. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +52 -10
  144. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -12
  145. data/sig/generated/paper_trail_diff/prepared_history.rbs +40 -24
  146. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +15 -13
  147. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +34 -2
  148. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +56 -11
  149. data/sig/generated/paper_trail_diff/recorded_changes.rbs +47 -0
  150. data/sig/generated/paper_trail_diff/recorded_class.rbs +22 -0
  151. data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
  152. data/sig/generated/paper_trail_diff/scope_condition.rbs +219 -0
  153. data/sig/generated/paper_trail_diff/scope_ranking.rbs +125 -0
  154. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
  155. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +8 -3
  156. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -11
  157. data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
  158. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +6 -0
  159. data/sig/generated/paper_trail_diff/support.rbs +20 -2
  160. data/sig/generated/paper_trail_diff/time_range.rbs +20 -2
  161. data/sig/generated/paper_trail_diff/time_version_range.rbs +4 -4
  162. data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -2
  163. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
  164. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
  165. data/sig/generated/paper_trail_diff/transaction_cut.rbs +94 -0
  166. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
  167. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +7 -0
  168. data/sig/generated/paper_trail_diff/version_boundary.rbs +20 -3
  169. data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
  170. data/sig/generated/paper_trail_diff/version_range.rbs +4 -2
  171. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +7 -4
  172. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -9
  173. data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
  174. data/sig/generated/paper_trail_diff.rbs +47 -25
  175. metadata +62 -10
  176. data/lib/paper_trail_diff/activity_grouping.rb +0 -38
  177. data/lib/paper_trail_diff/batch_safety.rb +0 -55
  178. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -224
  179. data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
  180. data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -24
  181. data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
@@ -9,39 +9,38 @@ 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
- # window. Joined duplicates are read in bounded pages and analyzed once.
41
+ # window. With `activity: true`, a change to a record on one of the
42
+ # requested association paths also counts, because the activity timeline
43
+ # reports it. Joined duplicates are read in bounded pages and analyzed once.
45
44
  #
46
45
  # `limit:` is required and exceeding it raises. Selection moves into the gem
47
46
  # here. The relation's own limit/offset select the live page; this separate
@@ -64,14 +63,19 @@ module PaperTrailDiff
64
63
  # Note also that a relation selects on current state, not on state during
65
64
  # the window: `where(status: 'published')` means published *now*, which is a
66
65
  # different set from what was published while the window was open.
67
- # : (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
68
- 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
69
68
 
70
- # Recent root and selected-child activity through the current saved state.
69
+ # Recent root and selected-child activity through the current saved state,
70
+ # for every root that changed or whose requested associations did.
71
71
  # Historical windows remain explicit on analyze_scope; this entry point is
72
72
  # deliberately named for a report through now rather than an as-of query.
73
- # : (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
74
- 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, ?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, ?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
75
79
 
76
80
  # Returns the association macros this release can normalize.
77
81
  # : () -> Array[Symbol]
@@ -81,9 +85,11 @@ module PaperTrailDiff
81
85
  # : (untyped, ?max_depth: Integer) -> Array[AssociationDescriptor]
82
86
  def self.association_paths: (untyped, ?max_depth: Integer) -> Array[AssociationDescriptor]
83
87
 
84
- # Reports known reconstruction hazards without mutating application state.
85
- # : (untyped, untyped, ?associations: Array[String | Symbol]) -> DiagnosticReport
86
- 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
87
93
 
88
94
  # Looks inside an attribute the database stores whole, such as a JSON or
89
95
  # jsonb column, and reports which keys changed.
@@ -105,6 +111,20 @@ module PaperTrailDiff
105
111
  # JSON uses for a present null.
106
112
  # : (untyped, ?untyped) -> nested_changes
107
113
  def self.nested_changes: (untyped, ?untyped) -> nested_changes
114
+
115
+ # Reads what PaperTrail recorded with one version: its `object_changes`,
116
+ # typed by the version's model, as `{ "title" => <from "Draft" to "Published"> }`.
117
+ # Activity methods read it for every step source with `recorded_changes: true`.
118
+ #
119
+ # A step's diff compares the states before and after an event, so it also
120
+ # includes anything saved without a version in between; this does not.
121
+ # Returns nil when nothing was recorded (no `object_changes` column, or no
122
+ # value for this version), which differs from a recorded empty hash. Unlike
123
+ # PaperTrail's `version.changeset`, it never loads the record, so it costs no
124
+ # query per version and still types a deleted record's changes. `ignore:`
125
+ # takes attribute names, as an array, and defaults to `updated_at`.
126
+ # : (untyped, ?ignore: Array[String | Symbol]) -> Hash[String, ValueChange]?
127
+ def self.recorded_changes: (untyped, ?ignore: Array[String | Symbol]) -> Hash[String, ValueChange]?
108
128
  end
109
129
 
110
130
  module PaperTrailDiff
@@ -130,10 +150,12 @@ module PaperTrailDiff
130
150
 
131
151
  type comparison_results = Hash[identity, Diff]
132
152
 
133
- 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 }
134
154
 
135
155
  type ignore_option = Array[String | Symbol] | Hash[String | Symbol, untyped]
136
156
 
157
+ type association_option = String | Symbol | Array[untyped] | Hash[untyped, untyped]
158
+
137
159
  type reference_key = :type | :id | "type" | "id"
138
160
 
139
161
  type traversal_context = :change | :included_state
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: paper_trail_diff
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.13.1
4
+ version: 0.15.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Alex Williams
@@ -9,6 +9,26 @@ bindir: bin
9
9
  cert_chain: []
10
10
  date: 1980-01-02 00:00:00.000000000 Z
11
11
  dependencies:
12
+ - !ruby/object:Gem::Dependency
13
+ name: activerecord
14
+ requirement: !ruby/object:Gem::Requirement
15
+ requirements:
16
+ - - ">="
17
+ - !ruby/object:Gem::Version
18
+ version: '7.1'
19
+ - - "<"
20
+ - !ruby/object:Gem::Version
21
+ version: '8.2'
22
+ type: :runtime
23
+ prerelease: false
24
+ version_requirements: !ruby/object:Gem::Requirement
25
+ requirements:
26
+ - - ">="
27
+ - !ruby/object:Gem::Version
28
+ version: '7.1'
29
+ - - "<"
30
+ - !ruby/object:Gem::Version
31
+ version: '8.2'
12
32
  - !ruby/object:Gem::Dependency
13
33
  name: paper_trail
14
34
  requirement: !ruby/object:Gem::Requirement
@@ -59,7 +79,6 @@ files:
59
79
  - lib/paper_trail_diff/activity_event_record_resolver.rb
60
80
  - lib/paper_trail_diff/activity_event_route_finder.rb
61
81
  - lib/paper_trail_diff/activity_event_snapshot_refresher.rb
62
- - lib/paper_trail_diff/activity_grouping.rb
63
82
  - lib/paper_trail_diff/activity_history.rb
64
83
  - lib/paper_trail_diff/activity_range.rb
65
84
  - lib/paper_trail_diff/activity_relationship.rb
@@ -67,30 +86,42 @@ files:
67
86
  - lib/paper_trail_diff/activity_root_steps.rb
68
87
  - lib/paper_trail_diff/activity_snapshot_delta.rb
69
88
  - lib/paper_trail_diff/activity_snapshot_sequence.rb
89
+ - lib/paper_trail_diff/activity_target_candidate_loader.rb
70
90
  - lib/paper_trail_diff/activity_timeline_builder.rb
71
91
  - lib/paper_trail_diff/activity_transaction_grouper.rb
92
+ - lib/paper_trail_diff/activity_tree_filter.rb
72
93
  - lib/paper_trail_diff/activity_version_collector.rb
94
+ - lib/paper_trail_diff/activity_view.rb
73
95
  - lib/paper_trail_diff/analysis.rb
74
96
  - lib/paper_trail_diff/analysis_batch.rb
97
+ - lib/paper_trail_diff/approximate_paths.rb
98
+ - lib/paper_trail_diff/association_activity_edge.rb
99
+ - lib/paper_trail_diff/association_activity_selection.rb
75
100
  - lib/paper_trail_diff/association_diff_traversal.rb
76
101
  - lib/paper_trail_diff/association_discovery.rb
102
+ - lib/paper_trail_diff/association_key.rb
77
103
  - lib/paper_trail_diff/association_traversal.rb
78
104
  - lib/paper_trail_diff/batch_boundary_resolver.rb
79
- - lib/paper_trail_diff/batch_safety.rb
105
+ - lib/paper_trail_diff/batch_preload.rb
80
106
  - lib/paper_trail_diff/batched_root_analyzer.rb
81
107
  - lib/paper_trail_diff/batched_root_versions.rb
82
108
  - lib/paper_trail_diff/branch_snapshot_refresher.rb
109
+ - lib/paper_trail_diff/change_row.rb
83
110
  - lib/paper_trail_diff/collection_comparator.rb
84
111
  - lib/paper_trail_diff/collection_identity_index.rb
85
112
  - lib/paper_trail_diff/collection_transition.rb
86
113
  - lib/paper_trail_diff/comparison_batch.rb
87
114
  - lib/paper_trail_diff/configuration.rb
88
115
  - lib/paper_trail_diff/deleted_analysis_batch.rb
116
+ - lib/paper_trail_diff/deleted_root_filter.rb
117
+ - lib/paper_trail_diff/deprecation.rb
89
118
  - lib/paper_trail_diff/diagnostics.rb
90
119
  - lib/paper_trail_diff/direct_record_state_loader.rb
91
120
  - lib/paper_trail_diff/endpoint.rb
92
121
  - lib/paper_trail_diff/engine.rb
93
122
  - lib/paper_trail_diff/errors.rb
123
+ - lib/paper_trail_diff/fallback_paths.rb
124
+ - lib/paper_trail_diff/habtm_transaction_owners.rb
94
125
  - lib/paper_trail_diff/historical_association_reifier.rb
95
126
  - lib/paper_trail_diff/historical_filter.rb
96
127
  - lib/paper_trail_diff/historical_snapshot_store.rb
@@ -110,8 +141,12 @@ files:
110
141
  - lib/paper_trail_diff/prepared_record_index.rb
111
142
  - lib/paper_trail_diff/prepared_snapshot_builder.rb
112
143
  - lib/paper_trail_diff/prepared_state_association_reader.rb
144
+ - lib/paper_trail_diff/recorded_changes.rb
145
+ - lib/paper_trail_diff/recorded_class.rb
113
146
  - lib/paper_trail_diff/root_version_plan.rb
114
147
  - lib/paper_trail_diff/root_version_selection.rb
148
+ - lib/paper_trail_diff/scope_condition.rb
149
+ - lib/paper_trail_diff/scope_ranking.rb
115
150
  - lib/paper_trail_diff/scoped_analysis.rb
116
151
  - lib/paper_trail_diff/scoped_analysis_builder.rb
117
152
  - lib/paper_trail_diff/scoped_root_selection.rb
@@ -121,12 +156,12 @@ files:
121
156
  - lib/paper_trail_diff/step.rb
122
157
  - lib/paper_trail_diff/stored_time_precision.rb
123
158
  - lib/paper_trail_diff/support.rb
124
- - lib/paper_trail_diff/time_activity_timeline_builder.rb
125
159
  - lib/paper_trail_diff/time_range.rb
126
160
  - lib/paper_trail_diff/time_version_range.rb
127
161
  - lib/paper_trail_diff/timeline_builder.rb
128
162
  - lib/paper_trail_diff/timeline_range.rb
129
163
  - lib/paper_trail_diff/timeline_snapshot_provider.rb
164
+ - lib/paper_trail_diff/transaction_cut.rb
130
165
  - lib/paper_trail_diff/traversal.rb
131
166
  - lib/paper_trail_diff/traversal_emitter.rb
132
167
  - lib/paper_trail_diff/traversal_entry.rb
@@ -139,6 +174,7 @@ files:
139
174
  - lib/paper_trail_diff/version_range.rb
140
175
  - lib/paper_trail_diff/version_scope_filter.rb
141
176
  - lib/paper_trail_diff/version_sequence_diagnostics.rb
177
+ - lib/paper_trail_diff/version_table.rb
142
178
  - sig/generated/paper_trail_diff.rbs
143
179
  - sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs
144
180
  - sig/generated/paper_trail_diff/activity_boundary.rbs
@@ -152,7 +188,6 @@ files:
152
188
  - sig/generated/paper_trail_diff/activity_event_record_resolver.rbs
153
189
  - sig/generated/paper_trail_diff/activity_event_route_finder.rbs
154
190
  - sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs
155
- - sig/generated/paper_trail_diff/activity_grouping.rbs
156
191
  - sig/generated/paper_trail_diff/activity_history.rbs
157
192
  - sig/generated/paper_trail_diff/activity_range.rbs
158
193
  - sig/generated/paper_trail_diff/activity_relationship.rbs
@@ -160,30 +195,42 @@ files:
160
195
  - sig/generated/paper_trail_diff/activity_root_steps.rbs
161
196
  - sig/generated/paper_trail_diff/activity_snapshot_delta.rbs
162
197
  - sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs
198
+ - sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs
163
199
  - sig/generated/paper_trail_diff/activity_timeline_builder.rbs
164
200
  - sig/generated/paper_trail_diff/activity_transaction_grouper.rbs
201
+ - sig/generated/paper_trail_diff/activity_tree_filter.rbs
165
202
  - sig/generated/paper_trail_diff/activity_version_collector.rbs
203
+ - sig/generated/paper_trail_diff/activity_view.rbs
166
204
  - sig/generated/paper_trail_diff/analysis.rbs
167
205
  - sig/generated/paper_trail_diff/analysis_batch.rbs
206
+ - sig/generated/paper_trail_diff/approximate_paths.rbs
207
+ - sig/generated/paper_trail_diff/association_activity_edge.rbs
208
+ - sig/generated/paper_trail_diff/association_activity_selection.rbs
168
209
  - sig/generated/paper_trail_diff/association_diff_traversal.rbs
169
210
  - sig/generated/paper_trail_diff/association_discovery.rbs
211
+ - sig/generated/paper_trail_diff/association_key.rbs
170
212
  - sig/generated/paper_trail_diff/association_traversal.rbs
171
213
  - sig/generated/paper_trail_diff/batch_boundary_resolver.rbs
172
- - sig/generated/paper_trail_diff/batch_safety.rbs
214
+ - sig/generated/paper_trail_diff/batch_preload.rbs
173
215
  - sig/generated/paper_trail_diff/batched_root_analyzer.rbs
174
216
  - sig/generated/paper_trail_diff/batched_root_versions.rbs
175
217
  - sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs
218
+ - sig/generated/paper_trail_diff/change_row.rbs
176
219
  - sig/generated/paper_trail_diff/collection_comparator.rbs
177
220
  - sig/generated/paper_trail_diff/collection_identity_index.rbs
178
221
  - sig/generated/paper_trail_diff/collection_transition.rbs
179
222
  - sig/generated/paper_trail_diff/comparison_batch.rbs
180
223
  - sig/generated/paper_trail_diff/configuration.rbs
181
224
  - sig/generated/paper_trail_diff/deleted_analysis_batch.rbs
225
+ - sig/generated/paper_trail_diff/deleted_root_filter.rbs
226
+ - sig/generated/paper_trail_diff/deprecation.rbs
182
227
  - sig/generated/paper_trail_diff/diagnostics.rbs
183
228
  - sig/generated/paper_trail_diff/direct_record_state_loader.rbs
184
229
  - sig/generated/paper_trail_diff/endpoint.rbs
185
230
  - sig/generated/paper_trail_diff/engine.rbs
186
231
  - sig/generated/paper_trail_diff/errors.rbs
232
+ - sig/generated/paper_trail_diff/fallback_paths.rbs
233
+ - sig/generated/paper_trail_diff/habtm_transaction_owners.rbs
187
234
  - sig/generated/paper_trail_diff/historical_association_reifier.rbs
188
235
  - sig/generated/paper_trail_diff/historical_filter.rbs
189
236
  - sig/generated/paper_trail_diff/historical_snapshot_store.rbs
@@ -203,8 +250,12 @@ files:
203
250
  - sig/generated/paper_trail_diff/prepared_record_index.rbs
204
251
  - sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs
205
252
  - sig/generated/paper_trail_diff/prepared_state_association_reader.rbs
253
+ - sig/generated/paper_trail_diff/recorded_changes.rbs
254
+ - sig/generated/paper_trail_diff/recorded_class.rbs
206
255
  - sig/generated/paper_trail_diff/root_version_plan.rbs
207
256
  - sig/generated/paper_trail_diff/root_version_selection.rbs
257
+ - sig/generated/paper_trail_diff/scope_condition.rbs
258
+ - sig/generated/paper_trail_diff/scope_ranking.rbs
208
259
  - sig/generated/paper_trail_diff/scoped_analysis.rbs
209
260
  - sig/generated/paper_trail_diff/scoped_analysis_builder.rbs
210
261
  - sig/generated/paper_trail_diff/scoped_root_selection.rbs
@@ -214,12 +265,12 @@ files:
214
265
  - sig/generated/paper_trail_diff/step.rbs
215
266
  - sig/generated/paper_trail_diff/stored_time_precision.rbs
216
267
  - sig/generated/paper_trail_diff/support.rbs
217
- - sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs
218
268
  - sig/generated/paper_trail_diff/time_range.rbs
219
269
  - sig/generated/paper_trail_diff/time_version_range.rbs
220
270
  - sig/generated/paper_trail_diff/timeline_builder.rbs
221
271
  - sig/generated/paper_trail_diff/timeline_range.rbs
222
272
  - sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs
273
+ - sig/generated/paper_trail_diff/transaction_cut.rbs
223
274
  - sig/generated/paper_trail_diff/traversal.rbs
224
275
  - sig/generated/paper_trail_diff/traversal_emitter.rbs
225
276
  - sig/generated/paper_trail_diff/traversal_entry.rbs
@@ -232,17 +283,18 @@ files:
232
283
  - sig/generated/paper_trail_diff/version_range.rbs
233
284
  - sig/generated/paper_trail_diff/version_scope_filter.rbs
234
285
  - sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs
286
+ - sig/generated/paper_trail_diff/version_table.rbs
235
287
  homepage: https://github.com/aheathwilliams/paper_trail_diff
236
288
  licenses:
237
289
  - MIT
238
290
  metadata:
239
291
  allowed_push_host: https://rubygems.org
240
292
  bug_tracker_uri: https://github.com/aheathwilliams/paper_trail_diff/issues
241
- changelog_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.13.1/CHANGELOG.md
242
- documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.13.1/README.md
293
+ changelog_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.15.0/CHANGELOG.md
294
+ documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.15.0/README.md
243
295
  homepage_uri: https://github.com/aheathwilliams/paper_trail_diff
244
296
  rubygems_mfa_required: 'true'
245
- source_code_uri: https://github.com/aheathwilliams/paper_trail_diff/tree/v0.13.1
297
+ source_code_uri: https://github.com/aheathwilliams/paper_trail_diff/tree/v0.15.0
246
298
  rdoc_options: []
247
299
  require_paths:
248
300
  - lib
@@ -1,38 +0,0 @@
1
- # frozen_string_literal: true
2
- # rbs_inline: enabled
3
-
4
- module PaperTrailDiff
5
- # Shared by the two activity builders. They differ in how they choose
6
- # boundaries -- one from an explicit version range, one from a wall-clock
7
- # window -- but a transaction has to collapse the same way in both, or the
8
- # same history would read differently depending on how it was asked for.
9
- module ActivityGrouping
10
- #: (Symbol?, ?activity: bool, ?snapshots: bool) -> void
11
- def self.validate!(group, activity: true, snapshots: false)
12
- unless group.nil? || group == :transaction
13
- raise ConfigurationError, 'group: must be :transaction or nil'
14
- end
15
- raise ConfigurationError, 'snapshots: requires activity: true' if snapshots && !activity
16
-
17
- return if group.nil? || activity
18
-
19
- raise ConfigurationError, 'group: requires activity: true'
20
- end
21
-
22
- private
23
-
24
- #: () -> bool
25
- def grouping?
26
- @group == :transaction
27
- end
28
-
29
- # Applied last, to finished steps, so grouping sees the same timeline the
30
- # caller would otherwise have received.
31
- #: (Array[ActivityStep]) -> Array[ActivityStep]
32
- def group_steps(steps)
33
- return steps unless grouping?
34
-
35
- ActivityTransactionGrouper.new(steps, retain: @snapshots).call
36
- end
37
- end
38
- end
@@ -1,55 +0,0 @@
1
- # frozen_string_literal: true
2
- # rbs_inline: enabled
3
-
4
- module PaperTrailDiff
5
- # Refuses known per-record association loading before a batch reconstructs it.
6
- class BatchSafety
7
- #: (AssociationTraversal, allow_expensive: bool) -> void
8
- def initialize(traversal, allow_expensive:)
9
- unless [true, false].include?(allow_expensive)
10
- raise ConfigurationError, 'allow_expensive: must be true or false'
11
- end
12
-
13
- @traversal = traversal
14
- @allow_expensive = allow_expensive
15
- end
16
-
17
- #: (untyped, ?historical: bool) -> void
18
- def call(model, historical: true)
19
- return if @allow_expensive
20
-
21
- @traversal.selected_reflections(model).each do |path, reflection|
22
- check(reflection, path, historical)
23
- end
24
- end
25
-
26
- private
27
-
28
- # @rbs @traversal: AssociationTraversal
29
- # @rbs @allow_expensive: bool
30
-
31
- #: (untyped, String, bool) -> void
32
- def check(reflection, path, historical)
33
- reason = reason_for(reflection, historical)
34
- if reason
35
- raise UnsupportedBatchPathError,
36
- "association #{path} requires per-record reconstruction (#{reason}); " \
37
- 'remove this path or explicitly pass allow_expensive: true'
38
- end
39
- return unless reflection.options[:through]
40
-
41
- check(reflection.through_reflection, path, historical)
42
- check(reflection.source_reflection, path, historical)
43
- end
44
-
45
- #: (untyped, bool) -> String?
46
- def reason_for(reflection, historical)
47
- return 'association scope' if reflection.scope
48
- return 'default-scoped target' if !reflection.polymorphic? && reflection.klass.default_scopes?
49
- return unless historical && reflection.options[:through]
50
- return if reflection.source_reflection.belongs_to?
51
-
52
- 'through source is not belongs_to'
53
- end
54
- end
55
- end