paper_trail_diff 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ee80500dbeb48421e7b0e0766a5f5559b73aa71528360a5f1a16866f9e6ccfa
-  data.tar.gz: 6692d3fd2d725918e16da15b4d39312b5e1a42deba3aa8e50a269abfd9fc6bd9
+  metadata.gz: 00ac8585544b9421fab5fa7cf677a5eddaae2867058beb2c7958ff0e8f917da5
+  data.tar.gz: 52e079e4f84b77ffd804fd452eaf4acc03618d2e7e685969faddcfe2f8c21eba
 SHA512:
-  metadata.gz: f809075c65c923ca0dd828e8337477d8461dfa13b2de537a9f99548f0826f867379a33c8bf4a5061476dabd1685829adc5ab21e07052a4d40ebfff4736a44946
-  data.tar.gz: 6212fab6601c900b2701a9401e7e9b66c5236f12da0340788f0641efef759340a29ea6f95e7b51d86c2792d847f5553db8f30d7c96e4370e37ceec0b8a227656
+  metadata.gz: 400361a0bd6d3d55b3637a5fdcb42febf04ff62a81b75aba3848f70c62d1865f7983016c31bb34347dc50df5b2f66ccb0e44306e2a31990c3db5c04f3806813e
+  data.tar.gz: 0b8497f1dcb9ecd6e12b09e28b7a69fe17363d251308abffb824e8d1d0033572c4bee71351785ed425dc5e46c656d092612c7cb4c1ff33e69ad270d8e2e7260b

data/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to this project will be documented in this file. The
 project follows [Semantic Versioning](https://semver.org/).
 
+## [0.10.0] - 2026-08-15
+
+### Added
+
+- Add `rake release:preflight`, which runs the full gate and then checks
+  everything that must hold before a tag: a clean working tree, a HEAD that
+  matches its upstream, an unused tag, a dated changelog section for the
+  version, and that the version is not already on RubyGems. It reports and
+  never tags, pushes, or publishes. An unreachable RubyGems is reported as
+  unknown rather than treated as "not published".
+- Raise `PaperTrailDiff::UnversionedAssociationError` when a selected
+  association's target is not versioned and history is being reconstructed.
+  Such a comparison could only ever answer "nothing changed", which is a wrong
+  answer rather than an empty one. Live-to-live comparison reads current state
+  and is unaffected. `diagnose` now reports the same condition as an error
+  rather than a warning, so `ok?` no longer stays true for a comparison that
+  will raise.
+- Document ActiveStorage attachments, which this reaches through:
+  `has_one_attached` points at models Rails owns and PaperTrail never versions,
+  so attachments are audited through a versioned model of your own that mirrors
+  the metadata onto ordinary columns.
+
 ## [0.9.0] - 2026-08-14
 
 ### Added

data/README.md

@@ -152,6 +152,55 @@ that touches a record and its children in quick succession will manage it — so
 this is worth checking before trusting an association history. Recording
 versions at sub-second precision separates them.
 
+### ActiveStorage attachments
+
+`has_one_attached` and `has_many_attached` point at `ActiveStorage::Attachment`
+and `ActiveStorage::Blob`, which Rails owns and PaperTrail does not version.
+There is no history behind them, so a historical comparison over those paths
+raises `PaperTrailDiff::UnversionedAssociationError` rather than reporting that
+nothing changed. Adding `has_paper_trail` to Rails' own models does not rescue
+it either: `has_one_attached` is a scoped `has_one`, and reifying it from
+history is ambiguous.
+
+Audit the attachment through a model you own instead. Give it the facts worth
+auditing as ordinary columns, and version it:
+
+```ruby
+class DocumentRevision < ApplicationRecord
+  belongs_to :attachable, polymorphic: true
+  has_one_attached :file
+  has_paper_trail
+
+  # Attaching a file writes to ActiveStorage's tables, not to this record, so
+  # nothing would be versioned without copying the facts across.
+  after_save :record_file_metadata, if: -> { file.attached? }
+
+  def record_file_metadata
+    blob = file.blob
+    return if filename == blob.filename.to_s && checksum == blob.checksum
+
+    update_columns(
+      filename: blob.filename.to_s, content_type: blob.content_type,
+      byte_size: blob.byte_size, checksum: blob.checksum
+    )
+  end
+end
+```
+
+```ruby
+class Article < ApplicationRecord
+  has_many :document_revisions, as: :attachable
+  has_paper_trail
+end
+
+PaperTrailDiff.compare(before, after, associations: [:document_revisions])
+```
+
+The bytes stay in ActiveStorage; the *auditable facts* live where PaperTrail
+can see them. Nothing about the column names matters to this gem — it reports
+whichever columns changed. What matters is that replacing a file writes to a
+versioned record, because attaching one on its own does not.
+
 ## Choosing an entry point
 
 | You need | Call |

data/lib/paper_trail_diff/diagnostics.rb

@@ -175,7 +175,9 @@ module PaperTrailDiff
     def inspect_versioned_model(model_class, path)
       return if model_versioned?(model_class)
 
-      add_warning(
+      # An error rather than a warning: `ok?` must not stay true for a
+      # comparison that cannot work, and this one raises at runtime.
+      add_error(
         :unversioned_association_target,
         "#{model_class.name} does not appear to have PaperTrail enabled",
         path

data/lib/paper_trail_diff/errors.rb

@@ -35,6 +35,10 @@ module PaperTrailDiff
   # Raised when a requested ActiveRecord association does not exist.
   class UnknownAssociationError < Error; end
 
+  # Raised when a selected association's target is not versioned, so its history
+  # cannot be reconstructed at all.
+  class UnversionedAssociationError < Error; end
+
   # Raised when a requested association macro is not supported.
   class UnsupportedAssociationError < Error; end
 

data/lib/paper_trail_diff/traversal_preparer.rb

@@ -17,6 +17,7 @@ module PaperTrailDiff
 
       ensure_association_tracking! if historical
       @traversal.validate!(model_class)
+      ensure_versioned_targets!(model_class) if historical
     end
 
     private
@@ -24,6 +25,30 @@ module PaperTrailDiff
     # @rbs @tree: AssociationTree
     # @rbs @traversal: AssociationTraversal
 
+    # A model PaperTrail never versioned has no history to reconstruct, so a
+    # comparison over it can only ever answer "nothing changed" -- which is a
+    # wrong answer rather than an empty one. Live-to-live comparison reads
+    # current state and is unaffected, so this applies to historical work only.
+    #: (untyped) -> void
+    def ensure_versioned_targets!(model_class)
+      @traversal.selected_reflections(model_class).each do |path, reflection|
+        # A polymorphic target is not known until a row names it; `diagnose`
+        # reports that separately rather than guessing here.
+        next if reflection.polymorphic?
+        next if versioned?(reflection.klass)
+
+        raise UnversionedAssociationError,
+              "association #{path} cannot be compared historically: " \
+              "#{reflection.klass.name} is not versioned. Add `has_paper_trail` to it, " \
+              'or mirror the fields you need onto a model that has it.'
+      end
+    end
+
+    #: (untyped) -> bool
+    def versioned?(model_class)
+      model_class.respond_to?(:paper_trail_options) && !model_class.paper_trail_options.nil?
+    end
+
     #: () -> void
     def ensure_association_tracking!
       paper_trail = Object.const_get(:PaperTrail) #: untyped

data/lib/paper_trail_diff/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module PaperTrailDiff
-  VERSION = '0.9.0'
+  VERSION = '0.10.0'
 end

data/sig/generated/paper_trail_diff/errors.rbs

@@ -45,6 +45,11 @@ module PaperTrailDiff
   class UnknownAssociationError < Error
   end
 
+  # Raised when a selected association's target is not versioned, so its history
+  # cannot be reconstructed at all.
+  class UnversionedAssociationError < Error
+  end
+
   # Raised when a requested association macro is not supported.
   class UnsupportedAssociationError < Error
   end

data/sig/generated/paper_trail_diff/traversal_preparer.rbs

@@ -16,6 +16,16 @@ module PaperTrailDiff
 
     @tree: AssociationTree
 
+    # A model PaperTrail never versioned has no history to reconstruct, so a
+    # comparison over it can only ever answer "nothing changed" -- which is a
+    # wrong answer rather than an empty one. Live-to-live comparison reads
+    # current state and is unaffected, so this applies to historical work only.
+    # : (untyped) -> void
+    def ensure_versioned_targets!: (untyped) -> void
+
+    # : (untyped) -> bool
+    def versioned?: (untyped) -> bool
+
     # : () -> void
     def ensure_association_tracking!: () -> void
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paper_trail_diff
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Alex Williams
@@ -202,11 +202,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.10.0/CHANGELOG.md
+  documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.10.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.10.0
 rdoc_options: []
 require_paths:
 - lib