feat: report a json gem that Rails cannot use

The json gem 3.x removed an option that Active Support older than
8.1.4 passes to the decoder. Each JSON column then raises
"unknown keyword: quirks_mode", and the cause is not clear from the
error.

The doctor now has a json check, and the boot prints a warning. Both
decode one document with Active Support. They do not compare version
numbers, so they stay correct when Rails or json changes. The gemspec
does not pin json, because a pin would stop applications on a Rails
release that supports json 3.

Author: cardmagic

docs/operations.md

@@ -43,6 +43,11 @@ an older Rails release, pin the 2.x series of `json`:
 gem "json", "~> 2"
 ```
 
+`bin/rails solid_objects:doctor` reports this problem as a failure of its
+`json` check, and the boot prints a warning that starts with
+`[solid_objects]`. Both decode one JSON document with Active Support. They do
+not compare version numbers.
+
 Review [CHANGELOG.md](../CHANGELOG.md) for compatibility and deployment-order
 notes, then update the gem:
 

lib/solid_objects.rb

@@ -20,6 +20,7 @@
 require "solid_objects/diagnostics"
 require "solid_objects/log_subscriber"
 require "solid_objects/serialization"
+require "solid_objects/json_compatibility"
 require "solid_objects/context"
 require "solid_objects/actor_registry"
 require "solid_objects/state"

lib/solid_objects/doctor.rb

@@ -99,21 +99,25 @@ def ping(value:)
 
     # @rbs @connection: untyped
     # @rbs @configuration: Configuration
+    # @rbs @json_compatibility: JsonCompatibility
 
-    # @rbs (?connection: untyped, ?configuration: Configuration) -> void
+    # @rbs (?connection: untyped, ?configuration: Configuration, ?json_compatibility: JsonCompatibility) -> void
     def initialize(
       connection: SolidObjects::Record.connection,
-      configuration: SolidObjects.configuration
+      configuration: SolidObjects.configuration,
+      json_compatibility: JsonCompatibility.new
     )
       @connection = connection
       @configuration = configuration
+      @json_compatibility = json_compatibility
     end
 
     # @rbs () -> Report
     def call
       configuration_check = check_configuration
       schema_check = check_schema
       checks = [
+        check_json,
         configuration_check,
         schema_check,
         check_authorization,
@@ -129,7 +133,15 @@ def call
 
     private
 
-    attr_reader :connection, :configuration
+    attr_reader :connection, :configuration, :json_compatibility
+
+    # @rbs () -> Check
+    def check_json
+      problem = json_compatibility.problem
+      return fail_check(:json, problem) if problem
+
+      pass(:json, "Active Support decodes JSON with the json gem #{JSON::VERSION}")
+    end
 
     # @rbs () -> Check
     def check_configuration

lib/solid_objects/engine.rb

@@ -15,6 +15,10 @@ class Engine < ::Rails::Engine
       SolidObjects::LogSubscriber.install
     end
 
+    initializer "solid_objects.json_compatibility" do
+      JsonCompatibility.new.warn_about_problem
+    end
+
     initializer "solid_objects.actors" do |application|
       application.config.to_prepare { ApplicationActorLoader.new.call }
     end

lib/solid_objects/json_compatibility.rb

@@ -0,0 +1,36 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class JsonCompatibility
+    PROBE = '{"probe":1}'
+
+    # @rbs @decode: ^(String) -> untyped
+
+    # @rbs (?decode: ^(String) -> untyped) -> void
+    def initialize(decode: ActiveSupport::JSON.method(:decode))
+      @decode = decode
+    end
+
+    # @rbs () -> String?
+    def problem
+      decode.call(PROBE)
+      nil
+    rescue ArgumentError => error
+      "Active Support #{ActiveSupport.version} cannot decode JSON with the json gem #{JSON::VERSION} " \
+        "(#{error.message}). Add gem \"json\", \"~> 2\" to the Gemfile, " \
+        "or use a Rails release that supports json 3"
+    end
+
+    # @rbs () -> void
+    def warn_about_problem
+      message = problem
+      return unless message
+
+      warn "[solid_objects] #{message}"
+    end
+
+    private
+
+    attr_reader :decode
+  end
+end

sig/generated/lib/solid_objects/doctor.rbs

@@ -47,12 +47,14 @@ module SolidObjects
       def ping: (value: String) -> String
     end
 
+    @json_compatibility: JsonCompatibility
+
     @configuration: Configuration
 
     @connection: untyped
 
-    # @rbs (?connection: untyped, ?configuration: Configuration) -> void
-    def initialize: (?connection: untyped, ?configuration: Configuration) -> void
+    # @rbs (?connection: untyped, ?configuration: Configuration, ?json_compatibility: JsonCompatibility) -> void
+    def initialize: (?connection: untyped, ?configuration: Configuration, ?json_compatibility: JsonCompatibility) -> void
 
     # @rbs () -> Report
     def call: () -> Report
@@ -63,6 +65,11 @@ module SolidObjects
 
     attr_reader configuration: untyped
 
+    attr_reader json_compatibility: untyped
+
+    # @rbs () -> Check
+    def check_json: () -> Check
+
     # @rbs () -> Check
     def check_configuration: () -> Check
 

sig/generated/lib/solid_objects/json_compatibility.rbs

@@ -0,0 +1,22 @@
+# Generated from lib/solid_objects/json_compatibility.rb with RBS::Inline
+
+module SolidObjects
+  class JsonCompatibility
+    PROBE: ::String
+
+    @decode: ^(String) -> untyped
+
+    # @rbs (?decode: ^(String) -> untyped) -> void
+    def initialize: (?decode: ^(String) -> untyped) -> void
+
+    # @rbs () -> String?
+    def problem: () -> String?
+
+    # @rbs () -> void
+    def warn_about_problem: () -> void
+
+    private
+
+    attr_reader decode: untyped
+  end
+end

test/integration/doctor_test.rb

@@ -27,6 +27,25 @@ class DoctorTest < ActiveSupport::TestCase
     assert_empty SolidObjects::Process.where(kind: "caller")
   end
 
+  test "passes the json check when Active Support decodes JSON" do
+    report = SolidObjects::Doctor.new.call
+
+    assert_equal :pass, report.check(:json).status
+    assert_includes report.check(:json).message, JSON::VERSION
+  end
+
+  test "fails the json check and names the correction when Active Support cannot decode JSON" do
+    refused = SolidObjects::JsonCompatibility.new(
+      decode: ->(_text) { raise ArgumentError, "unknown keyword: :quirks_mode" }
+    )
+
+    report = SolidObjects::Doctor.new(json_compatibility: refused).call
+
+    assert_not report.healthy?
+    assert_equal :fail, report.check(:json).status
+    assert_includes report.check(:json).message, 'gem "json", "~> 2"'
+  end
+
   test "runs its probe on a caller process the application cannot adopt" do
     SolidObjects.caller_process.define_singleton_method(:process_registry) do
       raise "the doctor probe must not share the application caller process"

test/unit/json_compatibility_test.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class JsonCompatibilityTest < ActiveSupport::TestCase
+  REFUSED_KEYWORD = ->(_text) { raise ArgumentError, "unknown keyword: :quirks_mode" }
+
+  test "reports no problem when Active Support decodes JSON" do
+    assert_nil SolidObjects::JsonCompatibility.new.problem
+  end
+
+  test "names the versions and the correction when Active Support cannot decode JSON" do
+    problem = SolidObjects::JsonCompatibility.new(decode: REFUSED_KEYWORD).problem
+
+    assert_includes problem, "unknown keyword: :quirks_mode"
+    assert_includes problem, "json gem #{JSON::VERSION}"
+    assert_includes problem, "Active Support #{ActiveSupport.version}"
+    assert_includes problem, 'gem "json", "~> 2"'
+  end
+
+  test "does not hide a different decode failure" do
+    broken = ->(_text) { raise NoMethodError, "decode is gone" }
+
+    assert_raises(NoMethodError) { SolidObjects::JsonCompatibility.new(decode: broken).problem }
+  end
+
+  test "warns on the error stream when there is a problem" do
+    _output, errors = capture_io { SolidObjects::JsonCompatibility.new(decode: REFUSED_KEYWORD).warn_about_problem }
+
+    assert_includes errors, "[solid_objects]"
+    assert_includes errors, 'gem "json", "~> 2"'
+  end
+
+  test "writes nothing when there is no problem" do
+    output, errors = capture_io { SolidObjects::JsonCompatibility.new.warn_about_problem }
+
+    assert_empty output
+    assert_empty errors
+  end
+
+  test "the engine checks JSON compatibility during the boot" do
+    names = SolidObjects::Engine.instance.initializers.map(&:name)
+
+    assert_includes names, "solid_objects.json_compatibility"
+  end
+end