paper_trail_diff 0.9.0 → 0.11.0

data/sig/generated/paper_trail_diff.rbs

@@ -27,14 +27,47 @@ module PaperTrailDiff
   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) -> 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, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Analysis
-  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) -> Analysis
+  # : (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
+  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
 
   # 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, ?version_scope: untyped, ?close_on: Symbol?) -> Hash[identity, Analysis]
-  def self.analyze_many: (Array[untyped], ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Hash[identity, Analysis]
+  #
+  # Pass `records` to analyze a list you assembled, which returns a Hash keyed
+  # by identity. Pass `scope:` with a `limit:` to have the roots selected for
+  # you from a relation, which returns a `ScopedAnalysis` -- the same Hash,
+  # plus the roots the relation could not reach. See `analyze_scope` for why
+  # that second collection exists.
+  # : (?Array[untyped]?, ?scope: untyped, ?limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> (Hash[identity, Analysis] | ScopedAnalysis)
+  def self.analyze_many: (?Array[untyped]?, ?scope: untyped, ?limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> (Hash[identity, Analysis] | ScopedAnalysis)
+
+  # Analyzes every root the relation reaches whose history moved inside the
+  # window, selecting them in a fixed number of queries rather than making the
+  # caller rediscover them.
+  #
+  # `limit:` is required and exceeding it raises. Selection moves into the gem
+  # here, so the bound on how much work a page can ask for has to move with
+  # it, and a truncated audit report is worse than a refused one.
+  #
+  # Returns a `ScopedAnalysis`, which destructures:
+  #
+  #   analyses, unreachable = PaperTrailDiff.analyze_scope(
+  #     Article.where(status: 'published'), within: july, limit: 500
+  #   )
+  #
+  # `unreachable` names roots that changed in the window but have no live row
+  # left. A relation's conditions are evaluated against the live table, so a
+  # destroyed root cannot be tested against them at all -- its history is
+  # intact and the state it held at destruction may well have matched. Those
+  # roots are reported rather than dropped so that a page auditing deletions
+  # is told where to look instead of quietly coming up short.
+  #
+  # Note also that a relation selects on current state, not on state during
+  # the window: `where(status: 'published')` means published *now*, which is a
+  # different set from what was published while the window was open.
+  # : (untyped, limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> ScopedAnalysis
+  def self.analyze_scope: (untyped, limit: Integer?, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> ScopedAnalysis
 
   # Returns the association macros this release can normalize.
   # : () -> Array[Symbol]
@@ -47,6 +80,27 @@ module PaperTrailDiff
   # Reports known reconstruction hazards without mutating application state.
   # : (untyped, untyped, ?associations: Array[String | Symbol]) -> DiagnosticReport
   def self.diagnose: (untyped, untyped, ?associations: Array[String | Symbol]) -> DiagnosticReport
+
+  # Looks inside an attribute the database stores whole, such as a JSON or
+  # jsonb column, and reports which keys changed.
+  #
+  #   change = diff.attributes.fetch('config')
+  #   PaperTrailDiff.nested_changes(change)
+  #   # => { ['theme'] => <from "dark" to "light">,
+  #   #      ['limits', 'max'] => <from 10 to 20> }
+  #
+  # Accepts the `ValueChange` an attribute diff already produced, or a bare
+  # pair. Returns an empty hash when the pair is not two readable structures,
+  # which is the honest answer: a column that held text on one side and JSON
+  # on the other changed wholesale, and the caller still has that change.
+  #
+  # Paths are arrays because a JSON key may contain a dot. Arrays are reported
+  # whole rather than by index, since their elements carry no identity and a
+  # list that merely shifted would otherwise look changed throughout. A key
+  # that was absent reads as `NestedComparator::ABSENT` rather than nil, which
+  # JSON uses for a present null.
+  # : (untyped, ?untyped) -> Hash[Array[String], ValueChange]
+  def self.nested_changes: (untyped, ?untyped) -> Hash[Array[String], ValueChange]
 end
 
 module PaperTrailDiff

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paper_trail_diff
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Alex Williams
@@ -55,6 +55,7 @@ files:
 - lib/paper_trail_diff/activity_event_record_resolver.rb
 - lib/paper_trail_diff/activity_event_route_finder.rb
 - lib/paper_trail_diff/activity_event_snapshot_refresher.rb
+- lib/paper_trail_diff/activity_grouping.rb
 - lib/paper_trail_diff/activity_history.rb
 - lib/paper_trail_diff/activity_range.rb
 - lib/paper_trail_diff/activity_relationship.rb
@@ -63,6 +64,7 @@ files:
 - 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_transaction_grouper.rb
 - lib/paper_trail_diff/activity_version_collector.rb
 - lib/paper_trail_diff/analysis.rb
 - lib/paper_trail_diff/analysis_batch.rb
@@ -89,6 +91,7 @@ files:
 - lib/paper_trail_diff/live_endpoint_batch_loader.rb
 - lib/paper_trail_diff/live_endpoint_provider.rb
 - lib/paper_trail_diff/live_graph_collector.rb
+- lib/paper_trail_diff/nested_comparator.rb
 - lib/paper_trail_diff/paper_trail_adapter.rb
 - lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb
 - lib/paper_trail_diff/prepared_association_reifier.rb
@@ -98,6 +101,8 @@ files:
 - lib/paper_trail_diff/prepared_record_index.rb
 - lib/paper_trail_diff/root_version_plan.rb
 - lib/paper_trail_diff/root_version_selection.rb
+- lib/paper_trail_diff/scoped_analysis.rb
+- lib/paper_trail_diff/scoped_root_selection.rb
 - lib/paper_trail_diff/snapshot.rb
 - lib/paper_trail_diff/snapshot_normalizer.rb
 - lib/paper_trail_diff/snapshot_traversal.rb
@@ -132,6 +137,7 @@ files:
 - sig/generated/paper_trail_diff/activity_event_record_resolver.rbs
 - sig/generated/paper_trail_diff/activity_event_route_finder.rbs
 - sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs
+- sig/generated/paper_trail_diff/activity_grouping.rbs
 - sig/generated/paper_trail_diff/activity_history.rbs
 - sig/generated/paper_trail_diff/activity_range.rbs
 - sig/generated/paper_trail_diff/activity_relationship.rbs
@@ -140,6 +146,7 @@ files:
 - 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_transaction_grouper.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
@@ -166,6 +173,7 @@ files:
 - sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs
 - sig/generated/paper_trail_diff/live_endpoint_provider.rbs
 - sig/generated/paper_trail_diff/live_graph_collector.rbs
+- sig/generated/paper_trail_diff/nested_comparator.rbs
 - sig/generated/paper_trail_diff/paper_trail_adapter.rbs
 - sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs
 - sig/generated/paper_trail_diff/prepared_association_reifier.rbs
@@ -175,6 +183,8 @@ files:
 - sig/generated/paper_trail_diff/prepared_record_index.rbs
 - sig/generated/paper_trail_diff/root_version_plan.rbs
 - sig/generated/paper_trail_diff/root_version_selection.rbs
+- sig/generated/paper_trail_diff/scoped_analysis.rbs
+- sig/generated/paper_trail_diff/scoped_root_selection.rbs
 - sig/generated/paper_trail_diff/snapshot.rbs
 - sig/generated/paper_trail_diff/snapshot_normalizer.rbs
 - sig/generated/paper_trail_diff/snapshot_traversal.rbs
@@ -202,11 +212,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.9.0/CHANGELOG.md
-  documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.9.0/README.md
+  changelog_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.11.0/CHANGELOG.md
+  documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.11.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.9.0
+  source_code_uri: https://github.com/aheathwilliams/paper_trail_diff/tree/v0.11.0
 rdoc_options: []
 require_paths:
 - lib