Introduce support for deprecated associations API

[stefannibrasil]

Closes #1681

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.

Example test cases

Assert association is deprecated:

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

Assert association is NOT deprecated:

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

Notes and Questions

• Added docs and coverage for all associations, let me know if I missed anything!
• What type of exception should I raise when the Active Record version is < 8.1? I didn't find an existing case to follow. NotImplementedError makes sense to me, although I debated on returning ArgumentError, since that's what ActiveRecord returns when trying to use it on versions < 8.1. Open to suggestions to provide more helpful error on older
  AR versions.
• I copied the rails_version check in the tests. Do you usually just check for rails versions or should I create a helper for checking active record instead? I am checking for ActiveRecord's version in the association class, since shoulda-matchers can be used in a non-Rails app.

Tests with a real app

I tested the code changes with these scripts: https://gist.github.com/stefannibrasil/02809758148838bf3950d34a64c37106 (Rails 8.0 and 8.1.1). Both provide lots of examples of how to use the new matcher.

[stefannibrasil]

I wanted to test the error message, but I can remove this context if it's too much.

[matsales28]

This is great, the only missing thing is that the deprecated association option will not exist in older rails versions, so you should only use the deprecated modifier method in the test.

expect do
            expect(having_many_children).to have_many(:children).deprecated(false)
          end.to raise_error(NotImplementedError, expected_message)

[stefannibrasil]

Thank you! Fixed it in 9450ae8

[matsales28]

Let's move this up before the line 375

# ... new doc
#
# @return [AssociationMatcher]

The same comment applies to the other doc comments.

[stefannibrasil]

Good catch, thanks! Done in 2239770

[matsales28]

We can have a new method in the lib/shoulda/matchers/rails_shim.rb file to have that active record version check.

[stefannibrasil]

Great idea! Refactored this in 9450ae8

[matsales28]

Let's leave the submatchers_match? as the last check, as they're usually a slower check.

[stefannibrasil]

Done in df61574

[matsales28]

We need tests that assert that the correct message output, e.g.

 it 'rejects an association with a non-matching :autosave option with the correct message' do
      message = 'Expected Vehicle to have a belongs_to association called drivable (drivable should have autosave set to true)'

      expect {
        expect(delegating_type_to_drivable(autosave: false)).to have_delegated_type(:drivable).autosave(true)
      }.to fail_with_message(message)
    end

[stefannibrasil]

Another great catch. I missed this test 🙈 Added these in 4ea3d9c

[stefannibrasil]

thanks @matsales28 for the review! I will come back to this tomorrow. Had some issues locally after pushing the branch and need to figure it out to fix the test.