Introduce support for deprecated associations API

Rails 8.1 introduced the ability to mark Active Record
associations as deprecated. This allows
developers to mark associations for deprecation while maintaining
backward compatibility.

Assert association is deprecated:

```ruby
it { should have_many(:posts).deprecated }
it { should have_one(:profile).deprecated }
it { should belong_to(:author).deprecated }
```

Assert association is NOT deprecated:

```ruby
it { should have_many(:posts).deprecated(false) }
```

Author: stefannibrasil

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]