Module: PaperTrailDiff

Defined in:
lib/paper_trail_diff.rb,
lib/paper_trail_diff/step.rb,
lib/paper_trail_diff/engine.rb,
lib/paper_trail_diff/errors.rb,
lib/paper_trail_diff/support.rb,
lib/paper_trail_diff/version.rb,
lib/paper_trail_diff/analysis.rb,
lib/paper_trail_diff/endpoint.rb,
lib/paper_trail_diff/snapshot.rb,
lib/paper_trail_diff/traversal.rb,
lib/paper_trail_diff/time_range.rb,
lib/paper_trail_diff/diagnostics.rb,
lib/paper_trail_diff/configuration.rb,
lib/paper_trail_diff/value_objects.rb,
lib/paper_trail_diff/version_range.rb,
lib/paper_trail_diff/activity_event.rb,
lib/paper_trail_diff/activity_range.rb,
lib/paper_trail_diff/analysis_batch.rb,
lib/paper_trail_diff/timeline_range.rb,
lib/paper_trail_diff/instrumentation.rb,
lib/paper_trail_diff/traversal_entry.rb,
lib/paper_trail_diff/activity_history.rb,
lib/paper_trail_diff/comparison_batch.rb,
lib/paper_trail_diff/prepared_history.rb,
lib/paper_trail_diff/timeline_builder.rb,
lib/paper_trail_diff/activity_boundary.rb,
lib/paper_trail_diff/root_version_plan.rb,
lib/paper_trail_diff/traversal_emitter.rb,
lib/paper_trail_diff/snapshot_traversal.rb,
lib/paper_trail_diff/time_version_range.rb,
lib/paper_trail_diff/traversal_preparer.rb,
lib/paper_trail_diff/activity_root_steps.rb,
lib/paper_trail_diff/paper_trail_adapter.rb,
lib/paper_trail_diff/snapshot_normalizer.rb,
lib/paper_trail_diff/live_graph_collector.rb,
lib/paper_trail_diff/prepared_edge_loader.rb,
lib/paper_trail_diff/version_scope_filter.rb,
lib/paper_trail_diff/activity_relationship.rb,
lib/paper_trail_diff/association_discovery.rb,
lib/paper_trail_diff/association_traversal.rb,
lib/paper_trail_diff/batched_root_analyzer.rb,
lib/paper_trail_diff/batched_root_versions.rb,
lib/paper_trail_diff/collection_comparator.rb,
lib/paper_trail_diff/collection_transition.rb,
lib/paper_trail_diff/prepared_record_index.rb,
lib/paper_trail_diff/live_endpoint_provider.rb,
lib/paper_trail_diff/root_version_selection.rb,
lib/paper_trail_diff/activity_snapshot_delta.rb,
lib/paper_trail_diff/batch_boundary_resolver.rb,
lib/paper_trail_diff/live_association_reader.rb,
lib/paper_trail_diff/prepared_history_loader.rb,
lib/paper_trail_diff/activity_timeline_builder.rb,
lib/paper_trail_diff/branch_snapshot_refresher.rb,
lib/paper_trail_diff/collection_identity_index.rb,
lib/paper_trail_diff/historical_snapshot_store.rb,
lib/paper_trail_diff/activity_snapshot_sequence.rb,
lib/paper_trail_diff/activity_version_collector.rb,
lib/paper_trail_diff/association_diff_traversal.rb,
lib/paper_trail_diff/live_endpoint_batch_loader.rb,
lib/paper_trail_diff/timeline_snapshot_provider.rb,
lib/paper_trail_diff/activity_event_route_finder.rb,
lib/paper_trail_diff/prepared_association_reifier.rb,
lib/paper_trail_diff/version_sequence_diagnostics.rb,
lib/paper_trail_diff/activity_event_record_resolver.rb,
lib/paper_trail_diff/historical_association_reifier.rb,
lib/paper_trail_diff/time_activity_timeline_builder.rb,
lib/paper_trail_diff/activity_child_candidate_loader.rb,
lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb,
lib/paper_trail_diff/activity_collection_route_change.rb,
lib/paper_trail_diff/activity_event_record_normalizer.rb,
lib/paper_trail_diff/activity_root_snapshot_refresher.rb,
lib/paper_trail_diff/activity_belongs_to_event_applier.rb,
lib/paper_trail_diff/activity_collection_event_applier.rb,
lib/paper_trail_diff/activity_collection_route_updater.rb,
lib/paper_trail_diff/activity_event_snapshot_refresher.rb,
lib/paper_trail_diff/activity_collection_record_updater.rb,
lib/paper_trail_diff/version_association_candidate_scope.rb,
sig/generated/paper_trail_diff.rbs,
sig/generated/paper_trail_diff.rbs,
sig/generated/paper_trail_diff/step.rbs,
sig/generated/paper_trail_diff/engine.rbs,
sig/generated/paper_trail_diff/errors.rbs,
sig/generated/paper_trail_diff/support.rbs,
sig/generated/paper_trail_diff/version.rbs,
sig/generated/paper_trail_diff/analysis.rbs,
sig/generated/paper_trail_diff/endpoint.rbs,
sig/generated/paper_trail_diff/snapshot.rbs,
sig/generated/paper_trail_diff/traversal.rbs,
sig/generated/paper_trail_diff/time_range.rbs,
sig/generated/paper_trail_diff/diagnostics.rbs,
sig/generated/paper_trail_diff/configuration.rbs,
sig/generated/paper_trail_diff/value_objects.rbs,
sig/generated/paper_trail_diff/version_range.rbs,
sig/generated/paper_trail_diff/activity_event.rbs,
sig/generated/paper_trail_diff/activity_range.rbs,
sig/generated/paper_trail_diff/analysis_batch.rbs,
sig/generated/paper_trail_diff/timeline_range.rbs,
sig/generated/paper_trail_diff/instrumentation.rbs,
sig/generated/paper_trail_diff/traversal_entry.rbs,
sig/generated/paper_trail_diff/activity_history.rbs,
sig/generated/paper_trail_diff/comparison_batch.rbs,
sig/generated/paper_trail_diff/prepared_history.rbs,
sig/generated/paper_trail_diff/timeline_builder.rbs,
sig/generated/paper_trail_diff/activity_boundary.rbs,
sig/generated/paper_trail_diff/root_version_plan.rbs,
sig/generated/paper_trail_diff/traversal_emitter.rbs,
sig/generated/paper_trail_diff/snapshot_traversal.rbs,
sig/generated/paper_trail_diff/time_version_range.rbs,
sig/generated/paper_trail_diff/traversal_preparer.rbs,
sig/generated/paper_trail_diff/activity_root_steps.rbs,
sig/generated/paper_trail_diff/paper_trail_adapter.rbs,
sig/generated/paper_trail_diff/snapshot_normalizer.rbs,
sig/generated/paper_trail_diff/live_graph_collector.rbs,
sig/generated/paper_trail_diff/prepared_edge_loader.rbs,
sig/generated/paper_trail_diff/version_scope_filter.rbs,
sig/generated/paper_trail_diff/activity_relationship.rbs,
sig/generated/paper_trail_diff/association_discovery.rbs,
sig/generated/paper_trail_diff/association_traversal.rbs,
sig/generated/paper_trail_diff/batched_root_analyzer.rbs,
sig/generated/paper_trail_diff/batched_root_versions.rbs,
sig/generated/paper_trail_diff/collection_comparator.rbs,
sig/generated/paper_trail_diff/collection_transition.rbs,
sig/generated/paper_trail_diff/prepared_record_index.rbs,
sig/generated/paper_trail_diff/live_endpoint_provider.rbs,
sig/generated/paper_trail_diff/root_version_selection.rbs,
sig/generated/paper_trail_diff/activity_snapshot_delta.rbs,
sig/generated/paper_trail_diff/batch_boundary_resolver.rbs,
sig/generated/paper_trail_diff/live_association_reader.rbs,
sig/generated/paper_trail_diff/prepared_history_loader.rbs,
sig/generated/paper_trail_diff/activity_timeline_builder.rbs,
sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs,
sig/generated/paper_trail_diff/collection_identity_index.rbs,
sig/generated/paper_trail_diff/historical_snapshot_store.rbs,
sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs,
sig/generated/paper_trail_diff/activity_version_collector.rbs,
sig/generated/paper_trail_diff/association_diff_traversal.rbs,
sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs,
sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs,
sig/generated/paper_trail_diff/activity_event_route_finder.rbs,
sig/generated/paper_trail_diff/prepared_association_reifier.rbs,
sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs,
sig/generated/paper_trail_diff/activity_event_record_resolver.rbs,
sig/generated/paper_trail_diff/historical_association_reifier.rbs,
sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs,
sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs,
sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs,
sig/generated/paper_trail_diff/activity_collection_route_change.rbs,
sig/generated/paper_trail_diff/activity_event_record_normalizer.rbs,
sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs,
sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs,
sig/generated/paper_trail_diff/activity_collection_event_applier.rbs,
sig/generated/paper_trail_diff/activity_collection_route_updater.rbs,
sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs,
sig/generated/paper_trail_diff/activity_collection_record_updater.rbs,
sig/generated/paper_trail_diff/version_association_candidate_scope.rbs

Overview

Structured version comparison for PaperTrail. Each method is a thin, documented entry point, so this reads as an API listing rather than logic.

Defined Under Namespace

Modules: ActivityRootSteps, Endpoint, Instrumentation, Support Classes: ActivityBelongsToEventApplier, ActivityBoundary, ActivityChildCandidateLoader, ActivityCollectionEventApplier, ActivityCollectionRecordUpdater, ActivityCollectionRouteChange, ActivityCollectionRouteUpdater, ActivityEvent, ActivityEventRecordNormalizer, ActivityEventRecordResolver, ActivityEventRegistry, ActivityEventRouteFinder, ActivityEventSnapshotRefresher, ActivityHistory, ActivityHistoryBuilder, ActivityRange, ActivityRelationship, ActivityRootSnapshotRefresher, ActivitySnapshotDelta, ActivitySnapshotProvider, ActivitySnapshotSequence, ActivityStep, ActivityTimelineBuilder, ActivityTransactionGroups, ActivityVersionCollector, AmbiguousVersionOrderError, Analysis, AnalysisBatch, AssociationDescriptor, AssociationDiscovery, AssociationSnapshot, AssociationTrackingUnavailableError, AssociationTraversal, AssociationTree, BatchBoundaryResolver, BatchedRootAnalyzer, BatchedRootVersions, BranchSnapshotRefresher, CollectionAssociationDiff, CollectionComparator, CollectionIdentityIndex, CollectionTransition, ComparisonBatch, ConfigurationError, DiagnosticIssue, DiagnosticReport, Diff, Engine, Error, HistoricalAssociationReifier, HistoricalSnapshotStore, HistoryDiagnostics, IgnorePolicy, IncompleteAssociationHistoryError, IncompleteTimeRangeError, InvalidEndpointError, InvalidTimeRangeError, InvalidTimelineRangeError, LiveAssociationReader, LiveEndpointBatchLoader, LiveEndpointProvider, LiveGraphCollector, PaperTrailAdapter, PreloadedEndpointBatchLoader, PreparedAssociationReifier, PreparedEdgeLoader, PreparedHistory, PreparedHistoryLoader, PreparedRecordIndex, PreparedRecordSeries, PreparedRecordState, PreparedVersionStateLoader, RecordChange, RecordReference, RecordSnapshot, ReversedEndpointsError, RootVersionPlan, RootVersionSelection, SnapshotNormalizer, SnapshotPool, Step, TimeActivityTimelineBuilder, TimeRange, TimeVersionRange, TimelineBuilder, TimelineRange, TimelineSnapshotProvider, ToOneAssociationDiff, TraversalEntry, TraversalPreparer, UnknownAssociationError, UnloadedAssociationError, UnsupportedAssociationError, UnsupportedLiveActivityError, ValueChange, VersionAssociationCandidateScope, VersionMismatchError, VersionRange, VersionScopeFilter, VersionSequenceDiagnostics

Constant Summary collapse

DEFAULT_IGNORED_ATTRIBUTES =

rubocop:disable Metrics/ModuleLength

Returns:

  • (Object) 
['updated_at'].freeze
SUPPORTED_ASSOCIATION_MACROS =

Returns:

  • (Object) 
%i[
  belongs_to
  has_one
  has_many
  has_and_belongs_to_many
].freeze
VERSION =

Returns:

  • (::String) 
'0.9.0'

Class Method Summary collapse

Class Method Details

.activity_timeline(record, from: nil, to: nil, within: nil, associations: [], ignore: DEFAULT_IGNORED_ATTRIBUTES, reload_live_endpoints: true, version_scope: nil, close_on: nil, snapshots: false) ⇒ Array[ActivityStep]

Compares adjacent root and selected-descendant activity boundaries. 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, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool) -> Array

Parameters:

  • (Object)
  • from: (Object) (defaults to: nil)
  • to: (Object) (defaults to: nil)
  • within: (Object) (defaults to: nil)
  • associations: (Array[String | Symbol]) (defaults to: [])
  • ignore: (ignore_option) (defaults to: DEFAULT_IGNORED_ATTRIBUTES)
  • reload_live_endpoints: (Boolean) (defaults to: true)
  • version_scope: (Object) (defaults to: nil)
  • close_on: (Symbol, nil) (defaults to: nil)
  • snapshots: (Boolean) (defaults to: false)

Returns:



174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/paper_trail_diff.rb', line 174

def activity_timeline( # rubocop:disable Metrics/ParameterLists
  record,
  from: nil,
  to: nil,
  within: nil,
  associations: [],
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
  reload_live_endpoints: true,
  version_scope: nil,
  close_on: nil,
  snapshots: false
)
  PaperTrailAdapter.new(
    associations: associations,
    ignore: ignore,
    reload_live_endpoints: reload_live_endpoints
  ).activity_timeline(
    record,
    from: from,
    to: to,
    within: within,
    version_scope: version_scope,
    close_on: close_on,
    snapshots: snapshots
  )
end

.analyze(record, from: nil, to: nil, within: nil, associations: [], ignore: DEFAULT_IGNORED_ATTRIBUTES, activity: false, version_scope: nil, close_on: nil, snapshots: false) ⇒ Analysis

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

Parameters:

  • (Object)
  • from: (Object) (defaults to: nil)
  • to: (Object) (defaults to: nil)
  • within: (Object) (defaults to: nil)
  • associations: (Array[String | Symbol]) (defaults to: [])
  • ignore: (ignore_option) (defaults to: DEFAULT_IGNORED_ATTRIBUTES)
  • activity: (Boolean) (defaults to: false)
  • version_scope: (Object) (defaults to: nil)
  • close_on: (Symbol, nil) (defaults to: nil)
  • snapshots: (Boolean) (defaults to: false)

Returns:



203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/paper_trail_diff.rb', line 203

def analyze( # rubocop:disable Metrics/ParameterLists
  record,
  from: nil,
  to: nil,
  within: nil,
  associations: [],
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
  activity: false,
  version_scope: nil,
  close_on: nil,
  snapshots: false
)
  PaperTrailAdapter.new(associations: associations, ignore: ignore).analyze(
    record,
    from: from,
    to: to,
    within: within,
    activity: activity,
    version_scope: version_scope,
    close_on: close_on,
    snapshots: snapshots
  )
end

.analyze_many(records, within: nil, associations: [], ignore: DEFAULT_IGNORED_ATTRIBUTES, activity: false, version_scope: nil, close_on: nil) ⇒ Hash[identity, 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, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?) -> Hash[identity, Analysis]

Parameters:

  • (Array[untyped])
  • within: (Object) (defaults to: nil)
  • associations: (Array[String | Symbol]) (defaults to: [])
  • ignore: (ignore_option) (defaults to: DEFAULT_IGNORED_ATTRIBUTES)
  • activity: (Boolean) (defaults to: false)
  • version_scope: (Object) (defaults to: nil)
  • close_on: (Symbol, nil) (defaults to: nil)

Returns:



231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/paper_trail_diff.rb', line 231

def analyze_many( # rubocop:disable Metrics/ParameterLists
  records,
  within: nil,
  associations: [],
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
  activity: false,
  version_scope: nil,
  close_on: nil
)
  PaperTrailAdapter.new(associations: associations, ignore: ignore).analyze_many(
    records,
    within: within,
    activity: activity,
    version_scope: version_scope,
    close_on: close_on
  )
end

.association_paths(model_or_record, max_depth: 1) ⇒ Array[AssociationDescriptor]

Discovers supported, finite association paths for a model or record. : (untyped, ?max_depth: Integer) -> Array

Parameters:

  • (Object)
  • max_depth: (Integer) (defaults to: 1)

Returns:



257
258
259
 
# File 'lib/paper_trail_diff.rb', line 257

def association_paths(model_or_record, max_depth: 1)
  AssociationDiscovery.new(model_or_record, max_depth: max_depth).call
end

.compare(from_version, to_version, associations: [], ignore: DEFAULT_IGNORED_ATTRIBUTES, reload_live_endpoints: true) ⇒ Diff

Compares net state between explicit PaperTrail-version or current-record endpoints. : (untyped, untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> Diff

Parameters:

  • (Object)
  • (Object)
  • associations: (Array[String | Symbol]) (defaults to: [])
  • ignore: (ignore_option) (defaults to: DEFAULT_IGNORED_ATTRIBUTES)
  • reload_live_endpoints: (Boolean) (defaults to: true)

Returns:



116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/paper_trail_diff.rb', line 116

def compare(
  from_version,
  to_version,
  associations: [],
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
  reload_live_endpoints: true
)
  PaperTrailAdapter.new(
    associations: associations,
    ignore: ignore,
    reload_live_endpoints: reload_live_endpoints
  ).compare(
    from_version,
    to_version
  )
end

.compare_many(comparisons, associations: [], ignore: DEFAULT_IGNORED_ATTRIBUTES, reload_live_endpoints: true) ⇒ comparison_results

Compares many independent endpoint pairs while batching current-record loading. : (Array, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool) -> comparison_results

Parameters:

  • (Array[comparison_input])
  • associations: (Array[String | Symbol]) (defaults to: [])
  • ignore: (ignore_option) (defaults to: DEFAULT_IGNORED_ATTRIBUTES)
  • reload_live_endpoints: (Boolean) (defaults to: true)

Returns:

  • (comparison_results) 


135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/paper_trail_diff.rb', line 135

def compare_many(
  comparisons,
  associations: [],
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
  reload_live_endpoints: true
)
  PaperTrailAdapter.new(
    associations: associations,
    ignore: ignore,
    reload_live_endpoints: reload_live_endpoints
  ).compare_many(comparisons)
end

.diagnose(from_version, to_version, associations: []) ⇒ DiagnosticReport

Reports known reconstruction hazards without mutating application state. : (untyped, untyped, ?associations: Array[String | Symbol]) -> DiagnosticReport

Parameters:

  • (Object)
  • (Object)
  • associations: (Array[String | Symbol]) (defaults to: [])

Returns:



263
264
265
 
# File 'lib/paper_trail_diff.rb', line 263

def diagnose(from_version, to_version, associations: [])
  HistoryDiagnostics.new(from_version, to_version, associations: associations).call
end

.supported_association_macros ⇒ Array[Symbol]

Returns the association macros this release can normalize. : () -> Array

Returns:

  • (Array[Symbol]) 


251
252
253
 
# File 'lib/paper_trail_diff.rb', line 251

def supported_association_macros
  SUPPORTED_ASSOCIATION_MACROS
end

.timeline(record, from: nil, to: nil, within: nil, associations: [], ignore: DEFAULT_IGNORED_ATTRIBUTES, version_scope: nil, close_on: nil) ⇒ Array[Step]

Compares every adjacent reconstructed state in an inclusive version range. : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?version_scope: untyped, ?close_on: Symbol?) -> Array

Parameters:

  • (Object)
  • from: (Object) (defaults to: nil)
  • to: (Object) (defaults to: nil)
  • within: (Object) (defaults to: nil)
  • associations: (Array[String | Symbol]) (defaults to: [])
  • ignore: (ignore_option) (defaults to: DEFAULT_IGNORED_ATTRIBUTES)
  • version_scope: (Object) (defaults to: nil)
  • close_on: (Symbol, nil) (defaults to: nil)

Returns:



150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/paper_trail_diff.rb', line 150

def timeline( # rubocop:disable Metrics/ParameterLists
  record,
  from: nil,
  to: nil,
  within: nil,
  associations: [],
  ignore: DEFAULT_IGNORED_ATTRIBUTES,
  version_scope: nil,
  close_on: nil
)
  PaperTrailAdapter.new(associations: associations, ignore: ignore).timeline(
    record,
    from: from,
    to: to,
    within: within,
    version_scope: version_scope,
    close_on: close_on
  )
end