Introduce support for deprecated associations API

lib/shoulda/matchers/active_record/association_matcher.rb

@@ -374,6 +374,25 @@ module ActiveRecord
       #
       # @return [AssociationMatcher]
       #
+      # ##### deprecated
+      #
+      # Use `deprecated` to assert that the `:deprecated` option was specified.
+      # (Enabled by default in Rails 8.1+).
+      #
+      #     class Account < ActiveRecord::Base
+      #       belongs_to :bank, deprecated: true
+      #     end
+      #
+      #     # RSpec
+      #     RSpec.describe Account, type: :model do
+      #       it { should belong_to(:bank).deprecated(true) }
+      #     end
+      #
+      #     # Minitest (Shoulda)
+      #     class AccountTest < ActiveSupport::TestCase
+      #       should belong_to(:bank).deprecated(true)
+      #     end
+      #
       def belong_to(name)
         AssociationMatcher.new(:belongs_to, name)
       end
@@ -683,7 +702,25 @@ def belong_to(name)
       #
       # @return [AssociationMatcher]
       #
-
+      # ##### deprecated
+      #
+      # Use `deprecated` to assert that the association is not allowed to be nil.
+      # (Enabled by default in Rails 8.1+).
+      #
+      #     class Vehicle < ActiveRecord::Base
+      #       delegated_type :drivable, types: %w(Car Truck), deprecated: true
+      #     end
+      #
+      #     # RSpec
+      #     describe Vehicle
+      #       it { should have_delegated_type(:drivable).deprecated }
+      #     end
+      #
+      #     # Minitest (Shoulda)
+      #     class VehicleTest < ActiveSupport::TestCase
+      #       should have_delegated_type(:drivable).deprecated
+      #     end
+      #
       def have_delegated_type(name)
         AssociationMatcher.new(:belongs_to, name)
       end
@@ -972,6 +1009,25 @@ def have_delegated_type(name)
       #
       # @return [AssociationMatcher]
       #
+      # ##### deprecated
+      #
+      # Use `deprecated` to assert that the `:deprecated` option was specified.
+      # (Enabled by default in Rails 8.1+)
+      #
+      #     class Player < ActiveRecord::Base
+      #       has_many :games, deprecated: true
+      #     end
+      #
+      #     # RSpec
+      #     RSpec.describe Player, type: :model do
+      #       it { should have_many(:games).deprecated(true) }
+      #     end
+      #
+      #     # Minitest (Shoulda)
+      #     class PlayerTest < ActiveSupport::TestCase
+      #       should have_many(:games).deprecated(true)
+      #     end
+      #
       def have_many(name)
         AssociationMatcher.new(:has_many, name)
       end
@@ -1219,6 +1275,25 @@ def have_many(name)
       #
       # @return [AssociationMatcher]
       #
+      # ##### deprecated
+      #
+      # Use `deprecated` to assert that the `:deprecated` option was specified.
+      # (Enabled by default in Rails 8.1+).
+      #
+      #     class Account < ActiveRecord::Base
+      #       has_one :bank, deprecated: true
+      #     end
+      #
+      #     # RSpec
+      #     RSpec.describe Account, type: :model do
+      #       it { should have_one(:bank).deprecated(true) }
+      #     end
+      #
+      #     # Minitest (Shoulda)
+      #     class AccountTest < ActiveSupport::TestCase
+      #       should have_one(:bank).deprecated(true)
+      #     end
+      #
       def have_one(name)
         AssociationMatcher.new(:has_one, name)
       end
@@ -1377,6 +1452,27 @@ def have_one(name)
       #
       # @return [AssociationMatcher]
       #
+      # ##### deprecated
+      #
+      # Use `deprecated` to assert that the `:deprecated` option was specified.
+      # (Enabled by default in Rails 8.1+).
+      #
+      #     class Publisher < ActiveRecord::Base
+      #       has_and_belongs_to_many :advertisers, deprecated: true
+      #     end
+      #
+      #     # RSpec
+      #     RSpec.describe Publisher, type: :model do
+      #       it { should have_and_belong_to_many(:advertisers).deprecated(true) }
+      #     end
+      #
+      #     # Minitest (Shoulda)
+      #     class AccountTest < ActiveSupport::TestCase
+      #       should have_and_belong_to_many(:advertisers).deprecated(true)
+      #     end
+      #
+      # @return [AssociationMatcher]
+      #
       def have_and_belong_to_many(name)
         AssociationMatcher.new(:has_and_belongs_to_many, name)
       end
@@ -1546,6 +1642,16 @@ def join_table(join_table_name)
           self
         end
 
+        def deprecated(deprecated = true)
+          if ::ActiveRecord::VERSION::STRING >= '8.1'
+            @options[:deprecated] = deprecated
+            self
+          else
+            raise NotImplementedError,
+              '`deprecated` association matcher is only available on Active Record >= 8.1.'
+          end
+        end
+
         def without_validating_presence
           remove_submatcher(AssociationMatchers::RequiredMatcher)
           self
@@ -1586,7 +1692,8 @@ def matches?(subject)
             touch_correct? &&
             types_correct? &&
             strict_loading_correct? &&
-            submatchers_match?
+            submatchers_match? &&
+            deprecated_correct?
         end
 
         def join_table_name
@@ -1848,6 +1955,15 @@ def touch_correct?
           end
         end
 
+        def deprecated_correct?
+          if option_verifier.correct_for_boolean?(:deprecated, options[:deprecated])
+            true
+          else
+            @missing = "#{name} should have deprecated: #{options[:deprecated]}"
+            false
+          end
+        end
+
         def types_correct?
           if options.key?(:types)
             types = options[:types]