paper_trail_diff 0.3.1 → 0.5.0

data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs

@@ -22,8 +22,25 @@ module PaperTrailDiff
 
     @tree: AssociationTree
 
-    # : () -> [ActivityHistory, Array[untyped]]
-    def history_and_versions: () -> [ ActivityHistory, Array[untyped] ]
+    # : () -> [ActivityHistory, Array[untyped], ActivityStep?]
+    def history_and_versions: () -> [ ActivityHistory, Array[untyped], ActivityStep? ]
+
+    # : (Array[untyped], Array[ActivityEvent]) -> ActivityHistory
+    def build_history: (Array[untyped], Array[ActivityEvent]) -> ActivityHistory
+
+    # : (ActivityHistory, ActivityStep?) -> Array[ActivityStep]
+    def activity_steps: (ActivityHistory, ActivityStep?) -> Array[ActivityStep]
+
+    # : (Array[ActivityEvent]) -> Array[ActivityEvent]
+    def selected_events: (Array[ActivityEvent]) -> Array[ActivityEvent]
+
+    # The window's last selected mutation is the root's own destruction, so the
+    # timeline closes on the absence it leaves rather than on a later boundary.
+    # : (ActivityHistory, ActivityEvent?) -> ActivityStep?
+    def closing_step: (ActivityHistory, ActivityEvent?) -> ActivityStep?
+
+    # : (ActivityEvent?) -> bool
+    def terminal_destroy?: (ActivityEvent?) -> bool
 
     # : (Array[untyped]) -> void
     def prepare_history: (Array[untyped]) -> void
@@ -31,16 +48,10 @@ module PaperTrailDiff
     # : (Array[untyped]) -> Array[ActivityEvent]
     def collect_events: (Array[untyped]) -> Array[ActivityEvent]
 
-    # : (Array[ActivityEvent]) -> bool
-    def time_events?: (Array[ActivityEvent]) -> bool
+    # : (Array[ActivityEvent], Array[ActivityEvent]) -> bool
+    def time_events?: (Array[ActivityEvent], Array[ActivityEvent]) -> bool
 
     # : (ActivityEvent, Array[ActivityEvent]) -> bool
     def later_event?: (ActivityEvent, Array[ActivityEvent]) -> bool
-
-    # : (Array[untyped], Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
-    def root_steps: (Array[untyped], Hash[Array[untyped], RecordSnapshot?]) -> Array[Step]
-
-    # : (untyped) -> Array[untyped]
-    def version_key: (untyped) -> Array[untyped]
   end
 end

data/sig/generated/paper_trail_diff/time_version_range.rbs

@@ -18,6 +18,13 @@ module PaperTrailDiff
     # : () -> untyped
     def versions_relation: () -> untyped
 
+    # A window closing on the record's own destruction needs no later version:
+    # the destroy reveals the preceding mutation and nothing can follow it, so
+    # demanding a checkpoint that can never be written would reject the range
+    # permanently.
+    # : (Array[untyped]) -> bool
+    def terminal_destroy?: (Array[untyped]) -> bool
+
     # : (untyped) -> untyped
     def trailing_version: (untyped) -> untyped
 

data/sig/generated/paper_trail_diff/timeline_builder.rbs

@@ -3,8 +3,8 @@
 module PaperTrailDiff
   # Selects and compares a chronological slice of a record's version history.
   class TimelineBuilder
-    # : (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped) -> void
-    def initialize: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped) -> void
+    # : (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?versions: Array[untyped]?) -> void
+    def initialize: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?versions: Array[untyped]?) -> void
 
     # : () -> Array[Step]
     def build: () -> Array[Step]

data/sig/generated/paper_trail_diff/timeline_range.rbs

@@ -3,15 +3,24 @@
 module PaperTrailDiff
   # Chooses explicit-version or wall-clock selection for one timeline request.
   class TimelineRange
+    BOUNDARY_SYMBOLS: untyped
+
     attr_reader from: untyped
 
     attr_reader to: untyped
 
     attr_reader time_range: TimeRange?
 
-    # : (untyped, from: untyped, to: untyped, within: untyped) -> void
-    def initialize: (untyped, from: untyped, to: untyped, within: untyped) -> void
+    # : (untyped, from: untyped, to: untyped, within: untyped, ?versions: Array[untyped]?) -> void
+    def initialize: (untyped, from: untyped, to: untyped, within: untyped, ?versions: Array[untyped]?) -> void
+
+    # A record with no versions has no first or last boundary to resolve, which
+    # is an empty history rather than a bad request.
+    # : () -> bool
+    def unresolved?: () -> bool
 
+    # A batch may have selected these versions already, in which case reselecting
+    # them per record would undo the batching.
     # : (?context_required: bool) -> Array[untyped]
     def select: (?context_required: bool) -> Array[untyped]
 
@@ -30,8 +39,32 @@ module PaperTrailDiff
 
     @record: untyped
 
+    @requested_from: untyped
+
+    @requested_to: untyped
+
     @to: untyped
 
+    @versions: Array[untyped]?
+
+    # : () -> Array[untyped]
+    def empty_versions: () -> Array[untyped]
+
+    # : (untyped) -> bool
+    def symbolic?: (untyped) -> bool
+
+    # Resolving `:first` and `:last` here keeps callers from depending on the
+    # order PaperTrail happens to give its versions association, which a caller
+    # is also free to reorder.
+    # : (untyped) -> untyped
+    def resolve: (untyped) -> untyped
+
+    # : () -> untyped
+    def ordered_versions: () -> untyped
+
+    # : () -> untyped
+    def versions_relation: () -> untyped
+
     # : (untyped) -> TimeRange?
     def build_time_range: (untyped) -> TimeRange?
 

data/sig/generated/paper_trail_diff/traversal_preparer.rbs

@@ -0,0 +1,22 @@
+# Generated from lib/paper_trail_diff/traversal_preparer.rb with RBS::Inline
+
+module PaperTrailDiff
+  # Checks that a model can be traversed before any reconstruction starts, and
+  # that association tracking is actually available when history is involved.
+  class TraversalPreparer
+    # : (tree: AssociationTree, traversal: AssociationTraversal) -> void
+    def initialize: (tree: AssociationTree, traversal: AssociationTraversal) -> void
+
+    # : (untyped, historical: bool) -> void
+    def call: (untyped, historical: bool) -> void
+
+    private
+
+    @traversal: AssociationTraversal
+
+    @tree: AssociationTree
+
+    # : () -> void
+    def ensure_association_tracking!: () -> void
+  end
+end

data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs

@@ -17,14 +17,27 @@ module PaperTrailDiff
 
     @version_class: untyped
 
+    # Only quoting helpers are needed, so the connection is borrowed for the
+    # duration of building the condition rather than checked out permanently,
+    # which Active Record 7.2 and newer can deprecate. Active Record 7.1 has no
+    # `with_connection` and reaches the same connection through the accessor.
+    # : () { (untyped) -> String } -> String
+    def with_connection: () { (untyped) -> String } -> String
+
     # : () -> String
     def candidate_condition: () -> String
 
-    # : (String, String) -> String
-    def activity_condition: (String, String) -> String
+    # : (untyped) -> String
+    def condition_sql: (untyped) -> String
+
+    # : (untyped, String, String) -> Hash[Symbol, String]
+    def quoted_columns: (untyped, String, String) -> Hash[Symbol, String]
+
+    # : (Hash[Symbol, String], String, untyped) -> String
+    def activity_condition: (Hash[Symbol, String], String, untyped) -> String
 
-    # : (String, String) -> String
-    def column: (String, String) -> String
+    # : (untyped, String, String) -> String
+    def column: (untyped, String, String) -> String
 
     # : (String) -> String
     def compact_sql: (String) -> String

data/sig/generated/paper_trail_diff.rbs

@@ -1,7 +1,9 @@
 # Generated from lib/paper_trail_diff.rb with RBS::Inline
 
-# Structured version comparison for PaperTrail.
+# Structured version comparison for PaperTrail. Each method is a thin,
+# documented entry point, so this reads as an API listing rather than logic.
 module PaperTrailDiff
+  # rubocop:disable Metrics/ModuleLength
   DEFAULT_IGNORED_ATTRIBUTES: untyped
 
   SUPPORTED_ASSOCIATION_MACROS: untyped
@@ -19,13 +21,21 @@ module PaperTrailDiff
   def self.timeline: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option) -> Array[Step]
 
   # Compares adjacent root and selected-descendant activity boundaries.
-  # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option) -> Array[ActivityStep]
-  def self.activity_timeline: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option) -> Array[ActivityStep]
+  # `reload_live_endpoints:` applies only when `to:` is a current record; the
+  # other range forms never read live state.
+  # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> Array[ActivityStep]
+  def self.activity_timeline: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> Array[ActivityStep]
 
   # Builds an endpoint diff and root-checkpoint timeline while normalizing each version once.
   # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool) -> Analysis
   def self.analyze: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool) -> Analysis
 
+  # Analyzes many roots over one shared time window, preparing their selected
+  # history once for the batch instead of once per record. Roots with no
+  # versions in the window return an empty `Analysis`.
+  # : (Array[untyped], ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool) -> Hash[identity, Analysis]
+  def self.analyze_many: (Array[untyped], ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool) -> Hash[identity, Analysis]
+
   # Returns the association macros this release can normalize.
   # : () -> Array[Symbol]
   def self.supported_association_macros: () -> Array[Symbol]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paper_trail_diff
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Alex Williams
@@ -59,14 +59,19 @@ files:
 - lib/paper_trail_diff/activity_range.rb
 - lib/paper_trail_diff/activity_relationship.rb
 - lib/paper_trail_diff/activity_root_snapshot_refresher.rb
+- lib/paper_trail_diff/activity_root_steps.rb
 - lib/paper_trail_diff/activity_snapshot_delta.rb
 - lib/paper_trail_diff/activity_snapshot_sequence.rb
 - lib/paper_trail_diff/activity_timeline_builder.rb
 - lib/paper_trail_diff/activity_version_collector.rb
 - lib/paper_trail_diff/analysis.rb
+- lib/paper_trail_diff/analysis_batch.rb
 - lib/paper_trail_diff/association_diff_traversal.rb
 - lib/paper_trail_diff/association_discovery.rb
 - lib/paper_trail_diff/association_traversal.rb
+- lib/paper_trail_diff/batch_boundary_resolver.rb
+- lib/paper_trail_diff/batched_root_analyzer.rb
+- lib/paper_trail_diff/batched_root_versions.rb
 - lib/paper_trail_diff/branch_snapshot_refresher.rb
 - lib/paper_trail_diff/collection_comparator.rb
 - lib/paper_trail_diff/collection_identity_index.rb
@@ -105,6 +110,7 @@ files:
 - lib/paper_trail_diff/traversal.rb
 - lib/paper_trail_diff/traversal_emitter.rb
 - lib/paper_trail_diff/traversal_entry.rb
+- lib/paper_trail_diff/traversal_preparer.rb
 - lib/paper_trail_diff/value_objects.rb
 - lib/paper_trail_diff/version.rb
 - lib/paper_trail_diff/version_association_candidate_scope.rb
@@ -126,14 +132,19 @@ files:
 - sig/generated/paper_trail_diff/activity_range.rbs
 - sig/generated/paper_trail_diff/activity_relationship.rbs
 - sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs
+- sig/generated/paper_trail_diff/activity_root_steps.rbs
 - sig/generated/paper_trail_diff/activity_snapshot_delta.rbs
 - sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs
 - sig/generated/paper_trail_diff/activity_timeline_builder.rbs
 - sig/generated/paper_trail_diff/activity_version_collector.rbs
 - sig/generated/paper_trail_diff/analysis.rbs
+- sig/generated/paper_trail_diff/analysis_batch.rbs
 - sig/generated/paper_trail_diff/association_diff_traversal.rbs
 - sig/generated/paper_trail_diff/association_discovery.rbs
 - sig/generated/paper_trail_diff/association_traversal.rbs
+- sig/generated/paper_trail_diff/batch_boundary_resolver.rbs
+- sig/generated/paper_trail_diff/batched_root_analyzer.rbs
+- sig/generated/paper_trail_diff/batched_root_versions.rbs
 - sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs
 - sig/generated/paper_trail_diff/collection_comparator.rbs
 - sig/generated/paper_trail_diff/collection_identity_index.rbs
@@ -172,6 +183,7 @@ files:
 - sig/generated/paper_trail_diff/traversal.rbs
 - sig/generated/paper_trail_diff/traversal_emitter.rbs
 - sig/generated/paper_trail_diff/traversal_entry.rbs
+- sig/generated/paper_trail_diff/traversal_preparer.rbs
 - sig/generated/paper_trail_diff/value_objects.rbs
 - sig/generated/paper_trail_diff/version.rbs
 - sig/generated/paper_trail_diff/version_association_candidate_scope.rbs
@@ -182,11 +194,11 @@ licenses:
 metadata:
   allowed_push_host: https://rubygems.org
   bug_tracker_uri: https://github.com/aheathwilliams/paper_trail_diff/issues
-  changelog_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.3.1/CHANGELOG.md
-  documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.3.1/README.md
+  changelog_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.5.0/CHANGELOG.md
+  documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.5.0/README.md
   homepage_uri: https://github.com/aheathwilliams/paper_trail_diff
   rubygems_mfa_required: 'true'
-  source_code_uri: https://github.com/aheathwilliams/paper_trail_diff/tree/v0.3.1
+  source_code_uri: https://github.com/aheathwilliams/paper_trail_diff/tree/v0.5.0
 rdoc_options: []
 require_paths:
 - lib