concerns_on_rails 1.28.2 → 1.28.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0a05169c98ce90531027509dbbdd4f00722678e2cfe246a5692484d9a12a111
-  data.tar.gz: 10d2cebdced9beed7b677b18a0b8c85dc82d1125672ada2f5c5f12b995fa1933
+  metadata.gz: d3f06aad189272886038354ad98dfd58a84642d64e1313c4aac5d88e7d1ec90a
+  data.tar.gz: b38acca4cb5cd6a48496d0d4909da90782c14b6b71748af88b72df482a02ef62
 SHA512:
-  metadata.gz: 756646b2232fa428250bf502fbb7ce87a44bf39830d9ae4810e50482315394fa1aa0b0e1ed47fb9a4b87d677d11507adfb7e14206f0b27119235060c74f1513b
-  data.tar.gz: '08b14db3a23711b0531447c773b2d831ec37fcf8c2b84fa59b4f203c7375923297e3a9dd93597b6e0091f18e677752be0dca67b913a4a3b1dd61fb042b417fad'
+  metadata.gz: 98d77a84da148195bdd1c013054b12bd3b8c4f6ce2bf5b7ae8ee7e91c0a24b4d5d45e6540c139456e1d51b91afbfaed5cf68d9faf9859399cb4ec2b76ccdd90b
+  data.tar.gz: 6852cb66a64150139c9625d765cd3f724881a6b35a9e5920140713c21b69f148c956353d587765f3ad1eca6018b38de70b98aa8aa9c40006ad0a6919242607c8

data/CHANGELOG.md

@@ -1,5 +1,59 @@
 <!-- CHANGELOG.md -->
 
+## 1.28.3 (2026-09-16)
+
+Three merged PRs from the September loop (#41, #43, #52), shipped as a patch at
+the maintainer's request: a SoftDeletable bug fix (`restore_all` /
+`really_destroy_all` dropped the caller's own predicate on the soft-delete
+column), a ColumnGuard change (every missing column reported in one error with
+one migration command) and an additive SoftDeletable `cascade:` option for
+has_many / has_one dependents. No new migrations or runtime dependencies.
+1396 examples, 0 failures.
+
+### Fixed
+- **Models::SoftDeletable**: `restore_all` and `really_destroy_all` now honour a
+  caller's predicate on the soft-delete column. Both used to `unscope` the
+  column outright to peel off the default scope's `deleted_at IS NULL`, which
+  also dropped `deleted_within(1.hour)` / `where(deleted_at: range)` /
+  `only_deleted` — so `User.deleted_within(1.hour).restore_all` restored the
+  whole trash can and `only_deleted.really_destroy_all` widened to the whole
+  relation. Only the default scope's own predicate is peeled now; predicates on
+  other columns (a host model's own `default_scope` included) are untouched. The
+  scopes themselves still unscope the column: chain `soft_deleted.where(...)`,
+  not `where(...).soft_deleted`. (#41)
+- **Models::Anonymizable**: the stamp column's migration hint now carries its
+  type (`anonymized_at:datetime`). (#43)
+
+### Changed
+- **Support::ColumnGuard**: a macro that finds several missing columns now
+  reports them all in one `ArgumentError` — `'street', 'city' and 'zip' do not
+  exist …` — with a single combined migration command
+  (`bin/rails generate migration AddAddressableColumnsToUsers street:string
+  city:string zip:string`) instead of failing boot once per column. Single-
+  column wording and generator name are unchanged. (#43)
+
+### Added
+- **Models::SoftDeletable**: `soft_deletable_by … cascade: %i[comments cover]`
+  soft-deletes has_many / has_one dependents with the record (same
+  transaction, same timestamp, through their own `soft_delete!` so hooks and
+  nested cascades run) and restores exactly those on `restore!` — a dependent
+  deleted independently earlier stays deleted. New `soft_delete!(at:)` keyword.
+  With a cascade configured, `soft_delete_all` / `restore_all` take the
+  per-record path. `belongs_to`, HABTM and `:through` are rejected at class
+  load; the target model must include SoftDeletable (checked at class load when
+  it already resolves, otherwise on the first cascade). (#52)
+
+### Notes
+`cascade:` is off by default — models without it behave exactly as before.
+`restore!` matches cascaded dependents by the parent's exact `deleted_at`, so
+give the columns `precision: 6` (the Rails 7 default) if two parents may be
+deleted within one second. With a cascade configured the single-`UPDATE` fast
+paths of `soft_delete_all` / `restore_all` are disabled (a bulk `UPDATE` cannot
+follow associations). Anything matching `/does not exist/` on a one-column
+ColumnGuard failure still matches — only the several-columns wording and
+generator name changed. The README's "use instead" table no longer lists
+association-cascade soft delete as a reason to reach for paranoia / discard.
+
 ## 1.28.2 (2026-09-11)
 
 Six merged enhancement PRs from the September loop (#42, #84, #59 via #90, #80,

data/README.md

@@ -146,9 +146,9 @@ across all 43 concerns — press <kbd>/</kbd> and type.
 - **Twenty-six model concerns + sixteen controller concerns**, all production-ready
 - **One include, one macro** — no boilerplate, no glue code
 - **Lean dependencies** — only `acts_as_list` (Sortable) and `friendly_id` (Sluggable), and both load **lazily**: an app that never includes those concerns never loads them. Depends on `activerecord`/`actionpack`/`activesupport`, not the full `rails` meta-gem; controller concerns have zero extra deps
-- **Schema-validated configuration** — every macro checks that the configured column exists and raises `ArgumentError` early — with a ready-to-paste `rails generate migration` hint when it doesn't
+- **Schema-validated configuration** — every macro checks that the configured columns exist and raises `ArgumentError` early — listing *every* missing column at once, with one ready-to-paste `rails generate migration` command that adds them all
 - **Composable** — concerns are independent; mix and match per model
-- **Tested like an app, not a snippet** — **1,360 RSpec examples** run against a real database on every CI build
+- **Tested like an app, not a snippet** — **1,396 RSpec examples** run against a real database on every CI build
 - **Documented twice** — everything in this README also lives as a per-concern page on the [docs site](https://vsn2015.github.io/concerns_on_rails), searchable and deep-linkable
 
 ---
@@ -467,13 +467,21 @@ User.soft_delete_all      # soft-deletes all matching records; returns the count
 User.destroy_all          # alias of soft_delete_all (kept for backwards compatibility; returns a count, not records)
 User.really_destroy_all   # hard-deletes the records matching the CURRENT relation (soft-deleted included)
 User.restore_all          # restores the matching soft-deleted records; returns the count
+
+User.deleted_within(1.hour).restore_all        # undo a bulk delete — only the last hour's trash
+User.deleted_within(30.days).really_destroy_all # purge recent trash; older rows untouched
+User.only_deleted.really_destroy_all           # empty the trash can, nothing else
 ```
 
 A record that fails to transition raises `ActiveRecord::RecordNotSaved` and rolls the whole
 batch back. With `touch: false` and no overridden hooks, `soft_delete_all` / `restore_all`
-collapse to a single `UPDATE`. Note that `really_destroy_all` peels the soft-delete
-predicate off the relation, so `only_deleted.really_destroy_all` widens to the whole
-relation — purge trash with `User.soft_deleted.delete_all` instead.
+collapse to a single `UPDATE`. Both `restore_all` and `really_destroy_all` peel off **only the
+default scope's own** `deleted_at IS NULL`: a predicate *you* put on the column — `deleted_within`,
+`where(deleted_at: range)`, `only_deleted` — survives, as does any other default scope the model
+declares. (Previously they unscoped the column outright, so `deleted_within(1.hour).restore_all`
+restored the whole trash can and `only_deleted.really_destroy_all` widened to the whole relation.)
+The *scopes* still unscope the column, so chain them first: `soft_deleted.where(...)`, not
+`where(...).soft_deleted`.
 
 **Scope-name collisions**
 
@@ -490,6 +498,30 @@ Expirable) without a collision. `prefix: true` uses the configured field name. W
 passed, scope names, the default scope, and the emitted SQL are unchanged. See the
 Publishable section above for how `prefix:`/`suffix:` differ across the gem.
 
+**Cascading to dependents**
+
+```ruby
+class Post < ApplicationRecord
+  include ConcernsOnRails::SoftDeletable
+  has_many :comments
+  has_one  :cover
+  soft_deletable_by :deleted_at, cascade: %i[comments cover]   # Comment and Cover include SoftDeletable too
+end
+
+post.soft_delete!        # comments + cover soft-deleted in the same transaction, with the post's exact timestamp
+post.restore!            # brings back the comments/cover the cascade deleted — NOT a comment someone trashed last week
+post.soft_delete!(at: 1.day.ago)   # new at: keyword — backdate, or hand a timestamp down a cascade
+```
+
+Dependents go through their own `soft_delete!` / `restore!` (hooks and nested cascades run). A dependent
+that fails — whether it raises or just fails validation — aborts the cascade with
+`ActiveRecord::RecordNotSaved` and rolls the parent back with it, so you never end up with a deleted
+parent and a live child. Declare the cascaded associations **above** `soft_deletable_by`; the macro
+resolves them at class load. Restore matches on the parent's timestamp, so independently
+deleted dependents keep their own. `cascade:` accepts `has_many` / `has_one` (no `belongs_to`, HABTM or
+`:through`) whose models include SoftDeletable; with a cascade configured `soft_delete_all` / `restore_all`
+take the per-record path (a bulk `UPDATE` cannot follow associations).
+
 **Lifecycle hooks** — override these methods on the model:
 
 ```ruby
@@ -2183,7 +2215,7 @@ Both forms reference the same module, so you can freely mix them.
 | Need | Use instead |
 |------|-------------|
 | Complex state machines (callbacks, transition logging) | [`aasm`](https://github.com/aasm/aasm) |
-| Association-cascade soft delete / sentinel-aware unique indexes | [`paranoia`](https://github.com/rubysherpas/paranoia) or [`discard`](https://github.com/jhawthorn/discard) |
+| Sentinel-aware unique indexes on soft-deleted rows (`deleted_at` in the index) | [`paranoia`](https://github.com/rubysherpas/paranoia) or [`discard`](https://github.com/jhawthorn/discard) |
 | Tagging with contexts, ownership, or tag clouds | [`acts-as-taggable-on`](https://github.com/mbleigh/acts-as-taggable-on) |
 | Full-text search with ranking / stemming | [`pg_search`](https://github.com/Casecommons/pg_search) / Elasticsearch |
 | Versioned audit trails with undo/reify, who-dunnit queries, or association tracking | [`paper_trail`](https://github.com/paper-trail-gem/paper_trail) / [`audited`](https://github.com/collectiveidea/audited) |
@@ -2217,9 +2249,9 @@ Point your agent at `llms.txt` for an overview, or paste a single concern's `.md
 
 ```sh
 bundle install                                  # install dev dependencies
-bundle exec rspec                               # run the test suite (1,360 examples)
+bundle exec rspec                               # run the test suite (1,396 examples)
 gem build concerns_on_rails.gemspec             # build the gem
-gem install ./concerns_on_rails-1.28.2.gem      # install locally
+gem install ./concerns_on_rails-1.28.3.gem      # install locally
 
 # Preview the docs site locally (GitHub Pages serves docs/ as-is):
 cd docs && python3 -m http.server 8000          # → http://localhost:8000

data/lib/concerns_on_rails/models/anonymizable.rb

@@ -96,7 +96,7 @@ module ConcernsOnRails
           anonymizable_apply_options(stamp, clear_audit_trail)
 
           ensure_columns!(LABEL, fields)
-          ensure_columns!(LABEL, anonymizable_stamp) if anonymizable_stamp
+          ensure_columns!(LABEL, anonymizable_stamp, types: :datetime) if anonymizable_stamp
           self.anonymizable_rules = anonymizable_rules.merge(fields.to_h { |f| [f.to_sym, strategy] })
 
           anonymizable_define_scopes(prefix, suffix)

data/lib/concerns_on_rails/models/soft_deletable.rb

@@ -22,6 +22,9 @@ module ConcernsOnRails
         class_attribute :soft_delete_scope_names, instance_accessor: false,
                                                   default: SCOPE_BASES.to_h { |b| [b, b] }.freeze
         class_attribute :soft_delete_captured_scopes, instance_accessor: false, default: {}.freeze
+        # has_many / has_one association names soft-deleted and restored along
+        # with this record (their models must include SoftDeletable too).
+        class_attribute :soft_delete_cascade, instance_accessor: false, default: [].freeze
 
         define_soft_delete_scopes(nil, nil)
         self.soft_delete_captured_scopes =
@@ -45,11 +48,23 @@ module ConcernsOnRails
         # Example:
         #   soft_deletable_by :deleted_at, touch: false
         #   soft_deletable_by :deleted_at, default_scope: false  # don't hide deleted rows from .all
-        def soft_deletable_by(field = nil, touch: true, default_scope: true, prefix: nil, suffix: nil)
+        #   soft_deletable_by :deleted_at, cascade: %i[comments attachments]
+        #
+        # `cascade:` names has_many / has_one associations whose records are
+        # soft-deleted with the parent (inside its transaction, with the
+        # parent's exact timestamp, through their own soft_delete! — hooks and
+        # nested cascades included) and restored with it. Restore only touches
+        # dependents carrying the parent's timestamp, so a comment someone
+        # deleted independently last week stays deleted when the post comes
+        # back. Every target model must include SoftDeletable. With a cascade
+        # configured the single-UPDATE batch fast paths are disabled, since a
+        # bulk UPDATE could not follow the associations.
+        def soft_deletable_by(field = nil, touch: true, default_scope: true, prefix: nil, suffix: nil, cascade: nil)
           self.soft_delete_field = field || :deleted_at
           self.soft_delete_touch = touch
           self.soft_delete_default_scope = default_scope
           ensure_columns!("ConcernsOnRails::Models::SoftDeletable", soft_delete_field, types: :datetime)
+          self.soft_delete_cascade = soft_delete_validate_cascade!(cascade)
           return unless prefix || suffix
 
           define_soft_delete_scopes(prefix, suffix)
@@ -82,22 +97,27 @@ module ConcernsOnRails
           soft_delete_all
         end
 
-        # Hard-delete every record matching the CURRENT relation — including
-        # soft-deleted rows (only the soft-delete column's predicates are
-        # peeled off). Note that `unscope` also drops a caller's own condition
-        # on that column, so `only_deleted.really_destroy_all` widens to the
-        # whole relation — use `soft_deleted.delete_all` to purge trash only.
+        # Hard-delete every record matching the CURRENT relation — soft-deleted
+        # rows included. Only the default scope's own `deleted_at IS NULL` is
+        # peeled off; a caller's predicate on the column survives, so
+        # `only_deleted.really_destroy_all` purges the trash and nothing else
+        # and `deleted_within(30.days).really_destroy_all` purges recent trash.
         # (Before 1.22 this ignored the relation entirely and hard-deleted the
-        # complete table.)
+        # complete table; until this fix it unscoped the column outright, which
+        # widened `only_deleted.really_destroy_all` to the whole relation.)
         def really_destroy_all
-          all.unscope(where: soft_delete_field).delete_all
+          soft_delete_without_default_scope.delete_all
         end
 
-        # Restore every soft-deleted record (mirror of soft_delete_all):
-        # Integer count, RecordNotSaved + rollback on failure, single UPDATE
-        # when the fast path applies.
+        # Restore every soft-deleted record in the relation (mirror of
+        # soft_delete_all): Integer count, RecordNotSaved + rollback on
+        # failure, single UPDATE when the fast path applies. Built against the
+        # current relation rather than routed through the `soft_deleted` scope,
+        # whose `unscope(where: deleted_at)` also stripped the CALLER's predicate
+        # on the column — `deleted_within(1.hour).restore_all` restored the
+        # whole trash can. (Same defect `publish_all` fixed in 1.27.)
         def restore_all
-          deleted = all.public_send(soft_delete_scope_names.fetch(:soft_deleted))
+          deleted = soft_delete_without_default_scope.where.not(soft_delete_field => nil)
           return deleted.update_all(soft_delete_field => nil) if soft_delete_batch_fast_path?(:restore)
 
           ConcernsOnRails::Support::BatchOps.run(
@@ -110,6 +130,27 @@ module ConcernsOnRails
 
         private
 
+        # The current relation with the DEFAULT SCOPE's soft-delete predicate
+        # peeled off — and nothing else. `unscope(where: field)` (what the
+        # scopes do) strips every predicate on the column, the caller's
+        # included; so unscope, then put back the predicates the caller added on
+        # that column. "Added by the caller" is the relation's where clause
+        # minus the default scope's own, using the same structural WhereClause
+        # arithmetic Rails' `merge`/`except` rely on. Predicates on OTHER
+        # columns — a host model's own `default_scope { where(tenant_id:) }`
+        # included — are never touched. With `default_scope: false` there is
+        # nothing to peel.
+        def soft_delete_without_default_scope
+          relation = all
+          return relation unless soft_delete_default_scope
+
+          callers = relation.where_clause - default_scoped.where_clause
+          callers_on_column = callers - callers.except(soft_delete_field.to_s)
+          peeled = relation.unscope(where: soft_delete_field)
+          peeled.where_clause += callers_on_column unless callers_on_column.empty?
+          peeled
+        end
+
         # Built here rather than inline in `included do` so the names can be
         # affixed. Every scope that references another scope resolves it
         # through soft_delete_scope_names — a hard-coded symbol would break
@@ -152,7 +193,7 @@ module ConcernsOnRails
         # reason: under `touch: false` both paths skip validations already, so
         # only the ownership half (`unoverridden?`) applies.
         def soft_delete_batch_fast_path?(kind)
-          return false if soft_delete_touch
+          return false if soft_delete_touch || soft_delete_cascade.any?
 
           methods = if kind == :restore
                       %i[before_restore after_restore restore!]
@@ -161,6 +202,47 @@ module ConcernsOnRails
                     end
           ConcernsOnRails::Support::BatchOps.unoverridden?(self, ConcernsOnRails::Models::SoftDeletable, *methods)
         end
+
+        # Each cascade target must be a has_many / has_one (not through) whose
+        # model includes SoftDeletable. The association shape is checked at
+        # class load; the target model is checked here when it already
+        # resolves, and otherwise on first cascade (a not-yet-loaded or
+        # anonymous class cannot be resolved from inside a class body).
+        def soft_delete_validate_cascade!(cascade)
+          names = Array(cascade).map(&:to_sym)
+          names.each do |name|
+            reflection = reflect_on_association(name)
+            raise ArgumentError, "#{soft_delete_label}: cascade: '#{name}' is not an association of #{self.name}" unless reflection
+            unless %i[has_many has_one].include?(reflection.macro)
+              raise ArgumentError,
+                    "#{soft_delete_label}: cascade: '#{name}' must be a has_many or has_one (got #{reflection.macro})"
+            end
+            if reflection.is_a?(ActiveRecord::Reflection::ThroughReflection)
+              raise ArgumentError, "#{soft_delete_label}: cascade: '#{name}' is a :through association; cascade to the source instead"
+            end
+
+            soft_delete_check_cascade_target!(name, reflection) if soft_delete_cascade_resolvable?(reflection)
+          end
+          names.freeze
+        end
+
+        def soft_delete_cascade_resolvable?(reflection)
+          reflection.klass
+          true
+        rescue NameError # NoMethodError (anonymous class: nil name) is a NameError
+          false
+        end
+
+        def soft_delete_check_cascade_target!(name, reflection)
+          return if reflection.klass.respond_to?(:soft_delete_field)
+
+          raise ArgumentError,
+                "#{soft_delete_label}: cascade: '#{name}' targets #{reflection.klass.name}, which does not include SoftDeletable"
+        end
+
+        def soft_delete_label
+          "ConcernsOnRails::Models::SoftDeletable"
+        end
       end
 
       # Soft delete hooks
@@ -169,7 +251,9 @@ module ConcernsOnRails
       def before_restore; end
       def after_restore; end
 
-      def soft_delete!
+      # `at:` sets the timestamp (default now) — it is what the cascade uses to
+      # hand the parent's exact timestamp down, and lets callers backdate.
+      def soft_delete!(at: Time.zone.now)
         return true if deleted?
 
         result = false
@@ -178,10 +262,11 @@ module ConcernsOnRails
         transaction do
           before_soft_delete
           result = if self.class.soft_delete_touch
-                     update(self.class.soft_delete_field => Time.zone.now)
+                     update(self.class.soft_delete_field => at)
                    else
-                     update_column(self.class.soft_delete_field, Time.zone.now)
+                     update_column(self.class.soft_delete_field, at)
                    end
+          soft_delete_cascade_dependents!(at) if result
           after_soft_delete if result
         end
         result
@@ -190,6 +275,7 @@ module ConcernsOnRails
       def restore!
         return true unless deleted?
 
+        stamp = self[self.class.soft_delete_field]
         result = false
         transaction do
           before_restore
@@ -198,6 +284,7 @@ module ConcernsOnRails
                    else
                      update_column(self.class.soft_delete_field, nil)
                    end
+          restore_cascaded_dependents!(stamp) if result
           after_restore if result
         end
         result
@@ -221,6 +308,54 @@ module ConcernsOnRails
       def is_really_deleted?
         !self.class.unscoped.exists?(id)
       end
+
+      private
+
+      # Soft-delete every not-yet-deleted dependent with the parent's timestamp.
+      # Goes through each record's own soft_delete! so its hooks and its own
+      # cascade run; a dependent deleted earlier keeps its own timestamp.
+      def soft_delete_cascade_dependents!(at)
+        soft_delete_each_dependent(deleted: false) do |dependent|
+          soft_delete_cascade_check!(dependent, dependent.soft_delete!(at: at), "soft-delete")
+        end
+      end
+
+      # Restore only the dependents that carry the parent's timestamp — the
+      # ones this cascade deleted — and let them restore their own dependents.
+      def restore_cascaded_dependents!(stamp)
+        soft_delete_each_dependent(deleted: stamp) do |dependent|
+          soft_delete_cascade_check!(dependent, dependent.restore!, "restore")
+        end
+      end
+
+      # A dependent that fails to save must not be skipped silently: with the
+      # default `touch: true` the write goes through `update`, which returns
+      # false on a validation failure instead of raising. Mirror the batch
+      # contract (Support::BatchOps) and raise RecordNotSaved, which rolls the
+      # whole cascade — and the parent's own change — back.
+      def soft_delete_cascade_check!(dependent, result, verb)
+        return if result
+
+        raise ActiveRecord::RecordNotSaved.new(
+          "#{self.class.send(:soft_delete_label)}: failed to cascade #{verb} to " \
+          "#{dependent.class.name}(id: #{dependent.id.inspect})", dependent
+        )
+      end
+
+      # Yields the records of every cascade association matching `deleted:`
+      # (false → not deleted, a timestamp → deleted at exactly that time).
+      # The association's default scope is peeled off so deleted rows are
+      # reachable; has_one is handled through the same relation.
+      def soft_delete_each_dependent(deleted:, &block)
+        self.class.soft_delete_cascade.each do |name|
+          reflection = self.class.reflect_on_association(name)
+          self.class.send(:soft_delete_check_cascade_target!, name, reflection)
+          field = reflection.klass.soft_delete_field
+          relation = association(name).scope.unscope(where: field)
+          relation = deleted ? relation.where(field => deleted) : relation.where(field => nil)
+          relation.find_each(&block)
+        end
+      end
     end
   end
 end

data/lib/concerns_on_rails/support/column_guard.rb

@@ -39,29 +39,52 @@ module ConcernsOnRails
       end
 
       # Same contract, validated against another class (e.g. CounterCacheable
-      # checks the counter column on the *parent* model).
+      # checks the counter column on the *parent* model). Every missing column
+      # is reported in ONE error — a fresh model with five absent columns is one
+      # migration away, not five boot failures.
       def ensure_columns_on!(concern, klass, *fields, types: nil)
         return false unless schema_reachable?(klass)
 
-        fields.flatten.compact.each do |field|
-          next if klass.column_names.include?(field.to_s)
+        missing = fields.flatten.compact.map(&:to_sym).uniq.reject { |field| klass.column_names.include?(field.to_s) }
+        return true if missing.empty?
 
-          raise ArgumentError,
-                "#{concern}: '#{field}' does not exist in the database (table: #{klass.table_name})." \
-                "#{column_migration_hint(klass, field, types)}"
-        end
-        true
+        raise ArgumentError, missing_columns_message(concern, klass, missing, types)
+      end
+
+      # "Concern: 'a' does not exist in the database (table: t). Add it with: …"
+      # for one column; "'a', 'b' and 'c' do not exist … Add them with: …" for
+      # several. The singular wording is unchanged from earlier releases.
+      def missing_columns_message(concern, klass, missing, types)
+        quoted = missing.map { |field| "'#{field}'" }
+        subject = if quoted.size == 1
+                    "#{quoted.first} does not exist"
+                  else
+                    "#{quoted[0..-2].join(', ')} and #{quoted.last} do not exist"
+                  end
+        "#{concern}: #{subject} in the database (table: #{klass.table_name})." \
+          "#{column_migration_hint(klass, missing, types, concern: concern)}"
       end
 
       # " Add it with: bin/rails generate migration AddDeletedAtToArticles
       # deleted_at:datetime" — every missing-column failure becomes a
-      # copy-paste fix. Without a known type the column name goes out bare
-      # (the generator defaults to string).
-      def column_migration_hint(klass, field, types)
-        type = types.is_a?(Hash) ? types[field.to_sym] : types
-        column = [field, type].compact.join(":")
-        " Add it with: bin/rails generate migration " \
-          "Add#{field.to_s.camelize}To#{klass.table_name.to_s.camelize} #{column}"
+      # copy-paste fix. Several columns get ONE command, named after the
+      # concern (AddAddressableColumnsToUsers street:string city:string) since
+      # AddStreetAndCityAndZipAndCountryTo… stops being readable. Without a
+      # known type the column name goes out bare (the generator defaults to
+      # string). Accepts a single field or a list.
+      def column_migration_hint(klass, fields, types, concern: nil)
+        fields = Array(fields)
+        columns = fields.map do |field|
+          type = types.is_a?(Hash) ? types[field.to_sym] : types
+          [field, type].compact.join(":")
+        end
+        table = klass.table_name.to_s.camelize
+        if fields.size == 1
+          " Add it with: bin/rails generate migration Add#{fields.first.to_s.camelize}To#{table} #{columns.first}"
+        else
+          " Add them with: bin/rails generate migration " \
+            "Add#{concern.to_s.demodulize}ColumnsTo#{table} #{columns.join(' ')}"
+        end
       end
 
       # True when the class's table can actually be inspected. Connection

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.28.2".freeze
+  VERSION = "1.28.3".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: concerns_on_rails
 version: !ruby/object:Gem::Version
-  version: 1.28.2
+  version: 1.28.3
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-11 00:00:00.000000000 Z
+date: 2026-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack