In Rails >= 5, use optional: true, not required: false

The `required` option on belongs_to associations has been deprecated,
instead the recommended (and default) approach is to set this to true by
default and disable it using `optional: true`.

The developer can override this default globally, however, so we can't
say that things like `optional: false` are superfluous, or indeed that
`required: true` isn't necessary.

This change therefore converts any use of `required` to it's inverse
`optional` equivalent.

See: https://guides.rubyonrails.org/5_0_release_notes.html

Author: petehamilton

config/enabled.yml

@@ -30,6 +30,12 @@ Rails/AssertNot:
   Description: 'Use `assert_not` instead of `assert !`.'
   Enabled: true
 
+Rails/BelongsTo:
+  Description: >-
+                  Use `optional: true` instead of `required: false` for
+                  `belongs_to` relations'
+  Enabled: true
+
 Rails/Blank:
   Description: 'Enforces use of `blank?`.'
   Enabled: true

lib/rubocop/cop/rails/belongs_to.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Rails
+      # This cop looks for belongs_to associations where we control whether the
+      # association is required via the deprecated `required` option instead.
+      #
+      # Since Rails 5, belongs_to associations are required by default and this
+      # can be controlled through the use of `optional: true`.
+      #
+      # From the release notes:
+      #
+      #     belongs_to will now trigger a validation error by default if the
+      #     association is not present. You can turn this off on a
+      #     per-association basis with optional: true. Also deprecate required
+      #     option in favor of optional for belongs_to. (Pull Request)
+      #
+      # In the case that the developer is doing `required: false`, we
+      # definitely want to autocorrect to `optional: true`.
+      #
+      # However, without knowing whether they've set overriden the default
+      # value of `config.active_record.belongs_to_required_by_default`, we
+      # can't say whether it's safe to remove `required: true` or whether we
+      # should replace it with `optional: false` (or, similarly, remove a
+      # superfluous `optional: false`). Therefore, in the cases we're using
+      # `required: true`, we'll simply invert it to `optional: false` and the
+      # user can remove depending on their defaults.
+      #
+      # @example
+      #   # bad
+      #   class Post < ApplicationRecord
+      #     belongs_to :blog, required: false
+      #   end
+      #
+      #   # good
+      #   class Post < ApplicationRecord
+      #     belongs_to :blog, optional: true
+      #   end
+      #
+      #   # bad
+      #   class Post < ApplicationRecord
+      #     belongs_to :blog, required: true
+      #   end
+      #
+      #   # good
+      #   class Post < ApplicationRecord
+      #     belongs_to :blog, optional: false
+      #   end
+      #
+      # @see https://guides.rubyonrails.org/5_0_release_notes.html
+      # @see https://github.com/rails/rails/pull/18937
+      class BelongsTo < Cop
+        extend TargetRailsVersion
+
+        minimum_target_rails_version 5.0
+
+        SUPERFLOUS_REQUIRE_FALSE_MSG =
+          'You specified `required: false`, in Rails > 5.0 the required ' \
+          'option is deprecated and you want to use `optional: true`.'.freeze
+
+        SUPERFLOUS_REQUIRE_TRUE_MSG =
+          'You specified `required: true`, in Rails > 5.0 the required ' \
+          'option is deprecated and you want to use `optional: false`. ' \
+          'In most configurations, this is the default and you can omit ' \
+          'this option altogether'.freeze
+
+        def_node_matcher :match_belongs_to_with_options, <<-PATTERN
+          (send $_ :belongs_to _ (hash $...))
+        PATTERN
+
+        def_node_matcher :match_required_false?, <<-PATTERN
+          (pair (sym :required) false)
+        PATTERN
+
+        def_node_matcher :match_required_true?, <<-PATTERN
+          (pair (sym :required) true)
+        PATTERN
+
+        def on_send(node)
+          opt = extract_required_option(node)
+          return unless opt
+          return unless match_required_true?(opt) || match_required_false?(opt)
+
+          message =
+            if match_required_true?(opt)
+              SUPERFLOUS_REQUIRE_TRUE_MSG
+            elsif match_required_false?(opt)
+              SUPERFLOUS_REQUIRE_FALSE_MSG
+            end
+
+          add_offense(node, message: message, location: :selector)
+        end
+
+        def autocorrect(node)
+          opt = extract_required_option(node)
+          return unless opt
+
+          lambda do |corrector|
+            if match_required_true?(opt)
+              corrector.replace(opt.loc.expression, 'optional: false')
+            elsif match_required_false?(opt)
+              corrector.replace(opt.loc.expression, 'optional: true')
+            end
+          end
+        end
+
+        def extract_required_option(node)
+          _, opts = match_belongs_to_with_options(node)
+          return unless opts
+
+          opts.find do |opt|
+            match_required_true?(opt) ||
+              match_required_false?(opt)
+          end
+        end
+      end
+    end
+  end
+end

lib/rubocop/cop/rails_cops.rb

@@ -14,6 +14,7 @@ module Cop
 require_relative 'rails/application_job'
 require_relative 'rails/application_record'
 require_relative 'rails/assert_not'
+require_relative 'rails/belongs_to'
 require_relative 'rails/blank'
 require_relative 'rails/bulk_change_table'
 require_relative 'rails/create_table_with_timestamps'

manual/cops_rails.md

@@ -162,6 +162,60 @@ Name | Default value | Configurable values
 --- | --- | ---
 Include | `**/test/**/*` | Array
 
+## Rails/BelongsTo
+
+Enabled by default | Supports autocorrection
+--- | ---
+Enabled | Yes
+
+This cop looks for belongs_to associations where we control whether the
+association is required via the deprecated `required` option instead.
+
+Since Rails 5, belongs_to associations are required by default and this
+can be controlled through the use of `optional: true`.
+
+From the release notes:
+
+    belongs_to will now trigger a validation error by default if the
+    association is not present. You can turn this off on a
+    per-association basis with optional: true. Also deprecate required
+    option in favor of optional for belongs_to. (Pull Request)
+
+In the case that the developer is doing `required: false`, we
+definitely want to autocorrect to `optional: true`.
+
+However, without knowing whether they've set overriden the default
+value of `config.active_record.belongs_to_required_by_default`, we
+can't say whether it's safe to remove `required: true` or whether we
+should replace it with `optional: false` (or, similarly, remove a
+superfluous `optional: false`). Therefore, in the cases we're using
+`required: true`, we'll simply invert it to `optional: false` and the
+user can remove depending on their defaults.
+
+### Examples
+
+```ruby
+# bad
+class Post < ApplicationRecord
+  belongs_to :blog, required: false
+end
+
+# good
+class Post < ApplicationRecord
+  belongs_to :blog, optional: true
+end
+
+# bad
+class Post < ApplicationRecord
+  belongs_to :blog, required: true
+end
+
+# good
+class Post < ApplicationRecord
+  belongs_to :blog, optional: false
+end
+```
+
 ## Rails/Blank
 
 Enabled by default | Supports autocorrection

spec/rubocop/cop/rails/belongs_to_spec.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+RSpec.describe RuboCop::Cop::Rails::BelongsTo do
+  subject(:cop) { described_class.new(config) }
+
+  let(:config) { RuboCop::Config.new }
+
+  it 'registers an offense when specifying `required: false`' do
+    expect_offense(<<-RUBY.strip_indent)
+      belongs_to :foo, required: false
+      ^^^^^^^^^^ You specified `required: false`, in Rails > 5.0 the required option is deprecated and you want to use `optional: true`.
+    RUBY
+  end
+
+  it 'registers an offense when specifying `required: true`' do
+    expect_offense(<<-RUBY.strip_indent)
+      belongs_to :foo, required: true
+      ^^^^^^^^^^ You specified `required: true`, in Rails > 5.0 the required option is deprecated and you want to use `optional: false`. In most configurations, this is the default and you can omit this option altogether
+    RUBY
+  end
+
+  it 'auto-corrects `required: false` to `optional: true`' do
+    expect(autocorrect_source('belongs_to :foo, required: false'))
+      .to eq('belongs_to :foo, optional: true')
+    expect(cop.offenses.last.status).to eq(:corrected)
+  end
+
+  it 'auto-corrects `required: true` to `optional: false`' do
+    code = 'belongs_to :foo, required: true'
+    expect(autocorrect_source(code))
+      .to eq('belongs_to :foo, optional: false')
+    expect(cop.offenses.last.status).to eq(:corrected)
+  end
+
+  it 'registers no offense when setting `optional: true`' do
+    expect_no_offenses('belongs_to :foo, optional: true')
+  end
+
+  it 'registers no offense when requires: false is not set' do
+    expect_no_offenses('belongs_to :foo')
+    expect_no_offenses('belongs_to :foo, polymorphic: true')
+  end
+end