conformance-kit 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7194b9197bb0f74d0984120097dcb41a80e518b9de1ba8818f0b0007b4614c09
-  data.tar.gz: d830a25c1493c79747f91312287f2b856f4450bd2f4636f6fd6bff9435c0ffcb
+  metadata.gz: 5a02143b58331881bf17f8f3fa4af58ed4a2e31293ecf91ec36c75dc6b88cf76
+  data.tar.gz: ccf2d81afca57e37ac74347deb18baba5a08a1ee592d2ec10580cdee0aecba6b
 SHA512:
-  metadata.gz: 387a7061b29d5f30d6bbc0316ca9d68601b981bce2b37a0afc5d03fa462e1bb3803a5ad3362bf822c106f154ab5b6df614a69e26eff5df0791294da79dc01353
-  data.tar.gz: 2b47a5f0f484b3b71382ae21630255b821d4bb420512b5cc6e2e5be69a3d44f2a9b79072c937d0644c8209e16320b5099bf4ceee450560f70ae7d94a06acb4cd
+  metadata.gz: 379a96c84f23be361de24dc24e55f66c313e00290b3fbe47b9b54fd4848f0ea02051aa3dc4c9186cf1f363d3584711e12c10a90f43e9ac0a4d37a9646d55bc6c
+  data.tar.gz: 8d4e996635a3e7b4b1d9b8d086d058c57fa6c16207b8f0d2a989aed19c9ed6ea9e22cdb0af000ebd178b99e3537704f5c30eb9aa0f929f9b24c1fa42ceb585d4

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.5.0 - 2026-10-18
+
+- `conformance-audit --require` and `audit.require` take a gem or feature name as well as a path: an entry that is not written as a path (`./`, `../`, `~`, absolute) and names no existing file is required from the load path. The kit now audits any installed gem with no Gemfile change and no `.conformance.yml`: `gem install conformance-kit` then `conformance-audit --require loofah --namespace Loofah`. Existing paths resolve as before.
+- README: how to try the audit on any gem, and a Minitest and an RSpec conformance case (the entry point in a non-main Ractor; every constant shareable) for gems that won't take the dependency.
+- The ractorize job (report-only, #22): `conformance-kit check --ractorize` boots `ractorize.app` in production with `ActiveSupport::Ractors.unshareable_proc_action = :raise`, calls `Rails.application.ractorize!`, serves each `ractorize.requests` path inside a non-main Ractor (a failure names the root cause and its first frame, also when an error page swallowed it) and audits `ractorize.audit_namespaces` (default `audit.namespace`) in the same process. It skips with the reason below Ruby 4.0 or on a Rails without `ractorize!`. New `.conformance.yml` keys: `ractorize.app`, `ractorize.requests`, `ractorize.audit_namespaces`, `ractorize.setup`.
+- `conformance.yml` gains a Ractorize job that runs when `ractorize.app` is set. It is `continue-on-error` until Rails 8.2 ships `ractorize!`, and bundles the repo with `config/ractorize.gemfile`: Rails main, Rack main and Shopify's i18n with Shopify/i18n#5, replacing the repo's own lines for them.
+
 ## 0.4.2 - 2026-10-17
 
 - A Proc or lock found inside another value now reads as one sentence: `[:save] is a Proc that is never shareable: ...` and `.@lock is a Thread::Mutex that is main-only: ...` instead of `is a Proc is never shareable` (in `conformance-audit` findings and `"a boot-finalized configuration"` failures; a top-level one reads `a Proc that is never shareable`).

data/README.md

@@ -1,6 +1,6 @@
 # conformance-kit
 
-Concurrency conformance for the zoolutions gems. A gem that adopts it is held to explicit tiers, each with a mechanical gate:
+Concurrency conformance for Ruby gems. Built for the zoolutions gems and usable by any gem: [audit a gem without adding anything to it](#try-it-on-any-gem), [copy the checks into your own tests](#a-conformance-case-without-the-kit), or adopt the kit. A gem that adopts it is held to explicit tiers, each with a mechanical gate:
 
 | Tier | Meaning | Gate |
 |---|---|---|
@@ -11,6 +11,102 @@ Concurrency conformance for the zoolutions gems. A gem that adopts it is held to
 
 Background, the finalize-at-boot pattern and the settled decisions: [zoolutions/phlex-reactive#363](https://github.com/zoolutions/phlex-reactive/issues/363).
 
+## Try it on any gem
+
+No Gemfile change and no `.conformance.yml`: install the kit, then name the gem to load and the namespace to audit.
+
+```bash
+gem install conformance-kit
+conformance-audit --require loofah --namespace Loofah
+```
+
+```
+conformance-audit: 42 findings in Loofah (0 allowlisted main-only; 38 modules audited, 0 unloaded autoloads skipped)
+  Loofah::Elements::BLOCK_LEVEL (constant) Set: a Set that is not frozen: freeze it at boot (Ractor.make_shareable)
+  ...
+  Loofah::Scrubbers::MAP (constant) Hash: a Hash that is not frozen: freeze it at boot (Ractor.make_shareable)
+report only: --strict fails on these
+```
+
+That is loofah 2.25.2 on Ruby 4.0.7: every finding is state a non-main Ractor cannot read. `--require` takes a gem or feature name (required from the load path, so any installed gem) or a file path, and repeats (`--require rack --require rack/mock_request`). Without `--strict` it only reports. What it can and can't see, and its exit codes: [`conformance-audit`](#conformance-audit).
+
+## A conformance case without the kit
+
+When a new development dependency is not an option (a framework, a gem that keeps its bundle small), the two checks that matter most fit in the gem's own tests. This is the shape of the case to attach to a compatibility pull request: it fails before the fix, passes after it, and fails again on the next constant that stops being shareable.
+
+```ruby
+# Minitest
+require "minitest/autorun" # or your test_helper
+
+class RactorConformanceTest < Minitest::Test
+  # State that is main-only on purpose, each with why.
+  MAIN_ONLY = { "MyGem::REGISTRY" => "apps add to it at boot" }.freeze
+
+  def setup
+    skip "needs Ruby 4.0 (Ractor#value)" unless defined?(Ractor) && Ractor.method_defined?(:value)
+  end
+
+  # The entry point runs inside a non-main Ractor and gives the main Ractor's answer.
+  def test_runs_inside_a_non_main_ractor
+    assert_equal MyGem.render("<p>hi</p>"), Ractor.new { MyGem.render("<p>hi</p>") }.value
+  end
+
+  # Every constant under MyGem is shareable, so the next mutable one fails here.
+  def test_constants_are_shareable
+    unshareable = constants_under(MyGem).reject { |name, value| MAIN_ONLY.key?(name) || Ractor.shareable?(value) }
+    assert_empty unshareable.map { |name, value| "#{name} (#{value.class})" }
+  end
+
+  private
+
+  def constants_under(mod)
+    mod.constants(false).reject { mod.autoload?(_1) }.flat_map do |name|
+      value = mod.const_get(name, false)
+      own = value.is_a?(Module) && value.name == "#{mod.name}::#{name}"
+      [["#{mod.name}::#{name}", value], *(own ? constants_under(value) : [])]
+    end
+  end
+end
+```
+
+```ruby
+# RSpec
+RSpec.describe "MyGem in a Ractor" do
+  main_only = { "MyGem::REGISTRY" => "apps add to it at boot" }.freeze
+
+  before { skip "needs Ruby 4.0 (Ractor#value)" unless defined?(Ractor) && Ractor.method_defined?(:value) }
+
+  it "runs the entry point inside a non-main Ractor" do
+    expect(Ractor.new { MyGem.render("<p>hi</p>") }.value).to eq(MyGem.render("<p>hi</p>"))
+  end
+
+  it "keeps every constant under MyGem shareable" do
+    walk = lambda do |mod|
+      mod.constants(false).reject { mod.autoload?(_1) }.flat_map do |name|
+        value = mod.const_get(name, false)
+        own = value.is_a?(Module) && value.name == "#{mod.name}::#{name}"
+        [["#{mod.name}::#{name}", value], *(own ? walk.call(value) : [])]
+      end
+    end
+    unshareable = walk.call(MyGem).reject { |name, value| main_only.key?(name) || Ractor.shareable?(value) }
+    expect(unshareable.map { |name, value| "#{name} (#{value.class})" }).to be_empty
+  end
+end
+```
+
+A failure names the constant and its class, e.g. `Expected ["MyGem::Html::ESCAPES (Hash)"] to be empty.` The Ractor block must not use outer local variables: write its input inline, or reach it through a constant.
+
+What these two leave out, and the kit covers:
+
+- class and module instance variables (a `@cache ||= {}` memo);
+- which value inside a constant is the problem: they name `MyGem::SETTINGS (Hash)`, the audit names `[:hooks] is a Proc that is never shareable`;
+- unloaded autoloads, which they skip without a word (the audit lists them);
+- races between threads and fibers.
+
+Neither sees a constant the gem defines under another namespace, such as an Active Job adapter in `ActiveJob::QueueAdapters`: walk that namespace too, or pass it to `--namespace`.
+
+## Adding it to a gem
+
 **A development dependency only.** Nothing here becomes a runtime dependency of your gem, and the kit adds none to your bundle: `async`, `minitest`, `rubocop-thread_safety` and `rubocop_spinel` are used only when you already have them. Ruby 3.2+; Ractor-only behaviour is gated on the running Ruby, never on a version floor.
 
 ```ruby
@@ -105,7 +201,7 @@ bundle exec conformance-audit --strict                                         #
 bundle exec conformance-audit --require ./lib/my_gem --namespace MyGem --strict # flags override them
 ```
 
-Requires the files, walks every loaded module under the namespaces (`--require` and `--namespace` repeat; without them it reads `audit.require` and `audit.namespace`), and reports each public constant and class/module instance variable whose value is not `Ractor.shareable?`, with the path to the offending object and the fix:
+Requires the files (an entry starting with `./`, `../`, `~` or `/` is a path; any other is required by name from the load path, as a gem, unless it names an existing file), walks every loaded module under the namespaces (`--require` and `--namespace` repeat; without them it reads `audit.require` and `audit.namespace`), and reports each public constant and class/module instance variable whose value is not `Ractor.shareable?`, with the path to the offending object and the fix:
 
 ```
 conformance-audit: 2 findings in MyGem (1 allowlisted main-only; 14 modules audited, 0 unloaded autoloads skipped)
@@ -147,6 +243,11 @@ probes:
   gem_name: my_gem                             # required for the probes job
   paths: [lib]                                 # default [lib]
   roundhouse_app: spec/dummy                   # optional
+ractorize:                                     # optional: the report-only ractorize job (below)
+  app: spec/dummy                              # the Rails app to boot, relative to this file
+  requests: ["/", "/widgets/1"]                # GET paths served inside a non-main Ractor
+  audit_namespaces: [MyGem]                    # default audit.namespace
+  setup: bin/rails db:prepare                  # optional, run in the app
 main_only:
   - name: MyGem::Registry.@lock                # class/module ivar: Owner.@ivar
     reason: guards boot-time registration; no non-main Ractor ever registers
@@ -204,11 +305,12 @@ jobs:
 
 To make it a merge requirement, add `conformance / Conformance settings` and `conformance / Conformance (Ruby 4.0)` to the required status checks in the repo's branch ruleset. Require both: if the settings job fails, the gate is skipped, and a skipped check does not block a merge. The prefix is the caller's job id (`conformance` above) and the Ruby is `ractor.ruby`, so the names change with either. Leave the probes out: they never fail. A repo or org that only allows selected actions must allow `zoolutions/conformance-kit/.github/workflows/conformance.yml@*`.
 
-The workflow has three jobs:
+The workflow has four jobs:
 
-- **Conformance settings** reads `ractor.ruby` and `ractor.working_directory`.
+- **Conformance settings** reads `ractor.ruby`, `ractor.working_directory` and `ractorize.app`.
 - **Conformance (Ruby `ractor.ruby`)**, the gate: the version handshake, then `bundle exec conformance-kit check`. A `postgres:18` service (user and password `postgres`, port 5432) is always up; the workflow exports nothing, so `ractor.env` and `ractor.setup` wire it.
 - **Compiler probes (report-only)**: `rubocop_spinel` (gem-installed in the probe, never in your Gemfile), `spinel-compat probe <probes.gem_name> --dir .` and, when `probes.roundhouse_app` is set, `roundhouse check` (the release tarball, checked against a pinned SHA-256). Every probe continues on error; the reports go to the run summary and a `conformance-probes` artifact. It never fails a build, and it skips with a notice when `probes.gem_name` is unset.
+- **Ractorize (report-only)**, only when `ractorize.app` is set: [the ractorize job](#the-ractorize-job-report-only) on Rails main. It never fails the workflow; leave it out of the required checks.
 
 ### Staying current
 
@@ -240,6 +342,7 @@ updates:
 
 ```bash
 bundle exec conformance-kit check    # doctor, ractor.setup, ractor.test_command, then conformance-audit --strict
+bundle exec conformance-kit check --ractorize   # the ractorize job (below), with BUNDLE_GEMFILE=Gemfile.ractorize
 bundle exec conformance-kit doctor   # the static checks only
 bundle exec conformance-kit config probes.gem_name
 ```
@@ -256,6 +359,63 @@ bundle exec conformance-kit config probes.gem_name
 | 1 | a check failed (`check` exits with the failing stage's status) |
 | 2 | usage error or an invalid `.conformance.yml` |
 
+### The ractorize job (report-only)
+
+Rails 8.2 can serve an app's requests from several Ractors: `Rails.application.ractorize!` makes the booted app shareable, and every gem on the request path has to cope. The Ruby 4.0 canary runs your gem's own code in a Ractor. This job runs it inside a real app that has been ractorized, where Rails' framework hooks, the app's boot order and other engines meet it.
+
+```yaml
+# .conformance.yml
+ractorize:
+  app: spec/dummy                    # the Rails app to boot (its config/environment.rb), relative to this file
+  requests: ["/", "/widgets/1"]      # GET paths, each served inside a non-main Ractor after ractorize!
+  audit_namespaces: [MyGem]          # audited after ractorize!; default audit.namespace
+  setup: bin/rails db:prepare db:schema:cache:dump assets:precompile   # optional
+```
+
+`conformance-kit check --ractorize` runs it locally, and the workflow's Ractorize job runs the same when `ractorize.app` is set:
+
+1. `ractorize.setup` runs in the app, with `ractor.env`, `RAILS_ENV=production` and `SECRET_KEY_BASE_DUMMY=1`.
+2. A new process sets `ActiveSupport::Ractors.unshareable_proc_action = :raise` and boots the app in production. The test environment can't serve a ractorized request yet ([rails/rails#59168](https://github.com/rails/rails/issues/59168)).
+3. It calls `Rails.application.ractorize!`, then `require "i18n/ractorize"`.
+4. Each request runs inside `Ractor.new`. An exception fails it, and so does a 5xx; either way the report names the root cause and its first frame, including an exception the app's error page swallowed.
+5. The audit runs on the namespaces in the same process, with `main_only:` applied, so it sees what a request Ractor reads.
+
+```
+ractorize: boot: ok
+ractorize: Rails.application.ractorize!: ok
+  GET /widget -> 500 (0 bytes): Ractor::IsolationError: can not get unshareable values from instance variables of classes/modules from non-main Ractors (@registry from MyGem::Widget)
+      at /home/runner/work/my_gem/my_gem/spec/dummy/app/controllers/widgets_controller.rb:5:in 'WidgetsController#show'
+ractorize: audit MyGem after ractorize!: 1 findings
+  MyGem::Widget.@registry (class ivar) Hash: [:names] is an Array that is not frozen: freeze it at boot (Ractor.make_shareable)
+ractorize failed: 2 failures (failed requests and audit findings)
+```
+
+A block Rails can't make shareable stops the boot, and Ruby's message names the block's file and line (`Proc's self is not shareable: #<Proc:... lib/my_gem/engine.rb:8>`). Below Ruby 4.0, or on a Rails without `ractorize!`, the job skips with the reason and exits 0.
+
+**What the app needs.** Production settings that can be made shareable, as in Rails' own `railties/test/application/ractors_test.rb`:
+
+- `config.enable_reloading = false` and `config.eager_load = true` (a generated `production.rb` sets both);
+- `config.logger = ActiveSupport::Ractors::Logger.new`;
+- `config.cache_store = :null_store`, `config.public_file_server.enabled = false`, `config.action_cable.mount_path = nil` and `config.active_job.queue_adapter = :inline`.
+
+With Active Record, it also needs a dumped schema cache (`db:schema:cache:dump`) and `config.active_record.check_schema_cache_dump_version = false`: without them, a model's first query inside a Ractor fails, and nothing warns. Precompile assets in `setup`. Framework state on your engine's classes is main-only, so list it once in `main_only:` (e.g. `ancestor: Rails::Engine` with `ivars: ["@called_from", "@initializers"]`).
+
+**The bundle.** Until they ship, `ractorize!` needs:
+
+- Rails main;
+- Rack main, for `rack/ractorize`;
+- Shopify's i18n branch, pinned to [Shopify/i18n#5](https://github.com/Shopify/i18n/pull/5) until that merges: without it, every render fails on `I18n.fallbacks`.
+
+`config/ractorize.gemfile` swaps them into your Gemfile. It drops your own lines for those gems and Rails' component gems (Bundler refuses a gem declared twice) and keeps everything else. Copy it next to your Gemfile and bundle with it, as the workflow does; keep `Gemfile.ractorize` and its lock out of git.
+
+```bash
+cp "$(bundle exec ruby -e 'print Gem.loaded_specs["conformance-kit"].full_gem_path')/config/ractorize.gemfile" Gemfile.ractorize
+BUNDLE_GEMFILE=Gemfile.ractorize bundle install
+BUNDLE_GEMFILE=Gemfile.ractorize bundle exec conformance-kit check --ractorize
+```
+
+**Report-only.** Rails main moves under it, so the job is `continue-on-error` and never fails the workflow until Rails 8.2 ships `ractorize!`. This repo proves it the same way, with a "Ractorize lane" in its own CI: a failing and a passing fixture app on that bundle.
+
 ### The version handshake
 
 The behaviour a repo is held to comes from the `conformance-kit` in its lockfile; only the plumbing comes from the workflow tag. So that a stale lockfile cannot pass a newer workflow vacuously, the workflow reads its own tag from `job.workflow_ref` (the called workflow's ref; `github.workflow_ref` is the caller's) and fails with "bump conformance-kit to ~> X.Y" when the repo resolves anything older than `X.Y`. The version is derived, never stored. When the caller pins anything other than a `vX.Y.Z` tag (a branch, a commit SHA, or this repo's own `./` caller) the handshake is skipped with a notice, and so it is on GitHub Enterprise Server, which has no `job.workflow_ref`.
@@ -264,6 +424,11 @@ The behaviour a repo is held to comes from the `conformance-kit` in its lockfile
 
 ```bash
 bundle exec rake   # rspec + rubocop; CI runs Ruby 3.2, 3.4 and 4.0
+
+# The ractorize lane (Ruby 4.0; CI's report-only "Ractorize lane" job)
+cp config/ractorize.gemfile Gemfile.ractorize
+BUNDLE_GEMFILE=Gemfile.ractorize bundle install
+BUNDLE_GEMFILE=Gemfile.ractorize bundle exec rspec --tag ractorize
 ```
 
 Every check is proven both ways against `spec/fixtures/`: a violating fixture it must catch and a conforming one it must pass. The kit audits itself (`.conformance.yml`, strict, nothing skipped), and `conformance.yml` runs on its own pull requests.

data/config/ractorize.gemfile

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# The ractorize job's bundle: the repo's own Gemfile, with Rails, Rack and i18n
+# swapped for the branches `Rails.application.ractorize!` needs until they ship
+# (Rails 8.2, Rack's rack/ractorize, ruby-i18n/i18n#741). Copy it next to the
+# repo's Gemfile as Gemfile.ractorize and run with BUNDLE_GEMFILE=Gemfile.ractorize.
+ractorize_sources = {
+  "rails" => { github: "rails/rails", branch: "main" },
+  "rack" => { github: "rack/rack", branch: "main" },
+  "i18n" => { github: "Shopify/i18n", ref: "refs/pull/5/head" }
+}.freeze
+# Rails' own gems come from the same checkout as rails.
+replaced = %w[railties actionpack actionview activesupport activemodel activerecord activejob actionmailer
+              actioncable activestorage actiontext actionmailbox] + ractorize_sources.keys
+
+# The repo's own lines for these gems are dropped: Bundler refuses a gem declared twice.
+reading_repo_gemfile = true
+define_singleton_method(:gem) do |name, *args, **options, &block|
+  super(name, *args, **options, &block) unless reading_repo_gemfile && replaced.include?(name)
+end
+
+eval_gemfile File.expand_path("Gemfile", __dir__)
+reading_repo_gemfile = false
+
+ractorize_sources.each { |name, source| gem name, **source }

data/lib/conformance_kit/audit/cli.rb

@@ -56,7 +56,7 @@ module ConformanceKit
       def parser(options)
         OptionParser.new do |o|
           o.banner = "Usage: conformance-audit [--require FILE] [--namespace CONST] [--strict] [--config PATH]"
-          o.on("--require FILE", "Require FILE before auditing (repeatable; default audit.require)") do |file|
+          o.on("--require FILE", "Require FILE or a gem by name first (repeatable; default audit.require)") do |file|
             options[:requires] << file
           end
           o.on("--namespace CONST", "Audit CONST and all under it (repeatable; default audit.namespace)") do |name|
@@ -78,7 +78,7 @@ module ConformanceKit
       def requires(options, config)
         return config.audit_requires if options[:requires].empty?
 
-        options[:requires].map { File.expand_path(_1) }
+        options[:requires].map { Config.require_target(_1, Dir.pwd) }
       end
 
       def check_namespace(name)

data/lib/conformance_kit/audit.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "conformance_kit"
+require_relative "../conformance_kit"
 require_relative "config"
 require_relative "audit/allowlist"
 require_relative "audit/cli"

data/lib/conformance_kit/cli/ractorize_check.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "open3"
+require "rbconfig"
+
+module ConformanceKit
+  class CLI
+    # `conformance-kit check --ractorize`: what the workflow's ractorize job
+    # runs. ractorize.setup in the app (RAILS_ENV=production), then the runner
+    # in its own process, both with ractor.env. Stops at the first failing stage.
+    class RactorizeCheck
+      BOOT = File.expand_path("../ractorize/boot.rb", __dir__).freeze
+      PRODUCTION = { "RAILS_ENV" => "production", "SECRET_KEY_BASE_DUMMY" => "1" }.freeze
+
+      def initialize(config, out:)
+        @config = config
+        @out = out
+        @app = config.ractorize_app
+        raise ConfigError, "#{config.source}: ractorize.app is not set (the Rails app to boot)" unless @app
+
+        environment = File.join(@app, "config/environment.rb")
+        return if File.file?(environment)
+
+        raise ConfigError, "#{config.source}: ractorize.app: #{environment} does not exist"
+      end
+
+      def run
+        setup = @config["ractorize.setup"]
+        code = setup ? shell(setup) : 0
+        return failed("ractorize.setup", code) unless code.zero?
+
+        code = runner
+        code.zero? ? code : failed("ractorize", code)
+      end
+
+      private
+
+      def env = @config["ractor.env"].merge(PRODUCTION)
+
+      def shell(command)
+        @out.puts "==> #{command}"
+        @out.flush
+        # system returns nil when the command could not be spawned at all.
+        return 127 if system(env, command, chdir: @app).nil?
+
+        Process.last_status.exitstatus || 1
+      end
+
+      def runner
+        @out.puts "==> ractorize #{@app}"
+        @out.flush
+        output, status = Open3.capture2e(env, RbConfig.ruby, BOOT, File.expand_path(@config.source), chdir: @app)
+        @out.print output
+        status.exitstatus || 1
+      end
+
+      def failed(stage, code)
+        @out.puts "conformance-kit check failed at #{stage} (exit #{code})"
+        code
+      end
+    end
+  end
+end

data/lib/conformance_kit/cli.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
 require "optparse"
-require "conformance_kit"
+require_relative "../conformance_kit"
 require_relative "config"
 require_relative "cli/doctor"
 require_relative "cli/check"
+require_relative "cli/ractorize_check"
 
 module ConformanceKit
-  # `conformance-kit check|doctor|config KEY [--config PATH] [--expect X.Y]`
+  # `conformance-kit check|doctor|config KEY [--config PATH] [--expect X.Y] [--ractorize]`
   #
   # Exit codes: 0 ok, 1 a check failed (`check` passes on its failing stage's
   # status), 2 usage or config error.
@@ -15,6 +16,8 @@ module ConformanceKit
     USAGE = <<~TEXT
       Usage: conformance-kit COMMAND [--config PATH]
         check [--expect X.Y]   doctor, ractor.setup, ractor.test_command, then conformance-audit --strict
+        check --ractorize      ractorize.setup, then boot ractorize.app with Rails.application.ractorize!,
+                               serve ractorize.requests inside non-main Ractors and audit (report-only job)
         doctor [--expect X.Y]  .conformance.yml, .rubocop.yml and the bundle are set up for the conformance workflow
         config KEY             print a .conformance.yml value (dotted key, e.g. probes.gem_name)
     TEXT
@@ -47,16 +50,17 @@ module ConformanceKit
       case command
       when "config" then print_value(options)
       when "doctor" then doctor(options).run
-      when "check" then Check.new(config(options), doctor(options), out: @out).run
+      when "check" then check(options)
       else raise ArgumentError, command ? "unknown command #{command}" : "no command"
       end
     end
 
     def parse(argv)
-      options = { config: Config::DEFAULT_PATH, expect: nil }
+      options = { config: Config::DEFAULT_PATH, expect: nil, ractorize: false }
       options[:args] = OptionParser.new do |o|
         o.on("--config PATH") { options[:config] = _1 }
         o.on("--expect X.Y") { options[:expect] = expected_version(_1) }
+        o.on("--ractorize") { options[:ractorize] = true }
       end.parse(argv)
       options
     end
@@ -69,6 +73,12 @@ module ConformanceKit
 
     def config(options) = Config.load(options[:config])
 
+    def check(options)
+      return RactorizeCheck.new(config(options), out: @out).run if options[:ractorize]
+
+      Check.new(config(options), doctor(options), out: @out).run
+    end
+
     def doctor(options)
       Doctor.new(config(options), out: @out, version: @version, specs: @specs, expect: options[:expect])
     end

data/lib/conformance_kit/config.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "rbconfig"
 require "yaml"
 require_relative "audit/allowlist"
 
@@ -13,6 +14,7 @@ module ConformanceKit
   #   audit:    { require: [], namespace: [], strict_autoloads: false, skip_autoloads: [] }
   #   ractor:   { ruby: "4.0", test_command: "...", env: {}, setup: nil, working_directory: "." }
   #   probes:   { gem_name: nil, paths: [lib], roundhouse_app: nil }
+  #   ractorize: { app: nil, requests: [], audit_namespaces: [audit.namespace], setup: nil }
   #   main_only: []
   class Config
     DEFAULT_PATH = ".conformance.yml"
@@ -30,6 +32,10 @@ module ConformanceKit
       "probes.gem_name" => :string,
       "probes.paths" => :list,
       "probes.roundhouse_app" => :string,
+      "ractorize.app" => :string,
+      "ractorize.requests" => :list,
+      "ractorize.audit_namespaces" => :list,
+      "ractorize.setup" => :string,
       "main_only" => :entries
     }.freeze
 
@@ -43,10 +49,11 @@ module ConformanceKit
       "ractor.env" => {}.freeze,
       "ractor.working_directory" => ".",
       "probes.paths" => ["lib"].freeze,
+      "ractorize.requests" => [].freeze,
       "main_only" => [].freeze
     }.freeze
 
-    SECTIONS = %w[audit ractor probes].freeze
+    SECTIONS = %w[audit ractor probes ractorize].freeze
 
     def self.load(path = DEFAULT_PATH)
       root = File.dirname(File.expand_path(path))
@@ -64,7 +71,9 @@ module ConformanceKit
       @source = source
       @root = root
       @exists = exists
-      raise ConfigError, "#{source}: expected a mapping (audit:, ractor:, probes:, main_only:)" unless data.is_a?(Hash)
+      unless data.is_a?(Hash)
+        raise ConfigError, "#{source}: expected a mapping (audit:, ractor:, probes:, ractorize:, main_only:)"
+      end
 
       pairs = flatten(data).each { |key, _| unknown_key!(key, TYPES.keys) unless TYPES.key?(key) }
       # A key left blank is unset: its default applies, as in the workflow's yq read.
@@ -82,10 +91,34 @@ module ConformanceKit
       @values.fetch(key) { DEFAULTS[key] }
     end
 
-    def audit_requires = self["audit.require"].map { File.expand_path(_1, root) }
+    # An `audit.require` or `--require` entry: a path relative to +base+ when
+    # written as one (`./lib/my_gem`, `/abs/path`) or when it names a Ruby file
+    # or native extension there, otherwise a feature for the load path, such as
+    # an installed gem.
+    def self.require_target(entry, base)
+      path = File.expand_path(entry, base)
+      explicit = entry.start_with?("./", "../", "~") || File.absolute_path?(entry)
+      explicit || requirable_file?(path) ? path : entry
+    end
+
+    def self.requirable_file?(path)
+      ["", ".rb", ".#{RbConfig::CONFIG['DLEXT']}"].any? { File.file?("#{path}#{_1}") }
+    end
+    private_class_method :requirable_file?
+
+    def audit_requires = self["audit.require"].map { self.class.require_target(_1, root) }
     def strict_autoloads? = self["audit.strict_autoloads"]
     def working_directory = File.expand_path(self["ractor.working_directory"], root)
 
+    # The Rails app the ractorize job boots, or nil when `ractorize.app` is unset.
+    def ractorize_app = self["ractorize.app"]&.then { File.expand_path(_1, root) }
+
+    # What the ractorize job audits after `ractorize!`: its own list, or audit.namespace.
+    def ractorize_namespaces
+      namespaces = self["ractorize.audit_namespaces"]
+      namespaces.nil? || namespaces.empty? ? self["audit.namespace"] : namespaces
+    end
+
     private
 
     def flatten(data)
@@ -100,9 +133,12 @@ module ConformanceKit
       end
     end
 
+    NAMESPACE_KEYS = %w[audit.namespace ractorize.audit_namespaces].freeze
+    private_constant :NAMESPACE_KEYS
+
     # A namespace is matched by name: `::MyGem` is `MyGem`, as with --namespace.
     def normalize(key, value)
-      key == "audit.namespace" ? value.map { _1.delete_prefix("::") } : value
+      NAMESPACE_KEYS.include?(key) ? value.map { _1.delete_prefix("::") } : value
     end
 
     def validate(key, value)

data/lib/conformance_kit/ractorize/boot.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# The ractorize job's process: `ruby boot.rb .conformance.yml`, under the
+# bundle that has Rails (BUNDLE_GEMFILE=Gemfile.ractorize). conformance-kit
+# check --ractorize starts it; it never runs inside the kit's own process.
+require_relative "runner"
+
+$stdout.sync = true
+exit ConformanceKit::Ractorize::Runner.new(ConformanceKit::Config.load(ARGV.fetch(0)), out: $stdout).run

data/lib/conformance_kit/ractorize/request.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module ConformanceKit
+  module Ractorize
+    # One request the ractorize job serves. Its env is built on the main Ractor
+    # from Strings only, so it crosses into the request Ractor as a copy; the
+    # IO objects Rack wants are made inside that Ractor.
+    module Request
+      SERVER = {
+        "SCRIPT_NAME" => "",
+        "SERVER_NAME" => "localhost",
+        "SERVER_PORT" => "80",
+        "SERVER_PROTOCOL" => "HTTP/1.1",
+        "HTTP_HOST" => "localhost",
+        "HTTP_ACCEPT" => "text/html",
+        "rack.url_scheme" => "http"
+      }.freeze
+
+      def self.env_for(path)
+        path_info, query = path.split("?", 2)
+        { "REQUEST_METHOD" => "GET", "PATH_INFO" => path_info, "QUERY_STRING" => query.to_s }.merge(SERVER)
+      end
+
+      # `{ status:, body:, error: }`, where error is describe_error's triple:
+      # the exception the app raised, or the one its error page swallowed.
+      def self.serve(app, path)
+        Ractor.new(app, env_for(path)) { |rack_app, env| Request.call(rack_app, env) }.value
+      end
+
+      # Runs inside the request Ractor.
+      def self.call(app, env)
+        env = env.merge("rack.input" => StringIO.new(+""), "rack.errors" => StringIO.new)
+        status, _headers, body = app.call(env)
+        text = read(body)
+        swallowed = env["action_dispatch.exception"]
+        { status: status, body: text, error: swallowed && describe_error(swallowed) }
+      rescue Exception => e # rubocop:disable Lint/RescueException -- every failure is the report
+        { status: nil, body: nil, error: describe_error(e) }
+      end
+
+      def self.read(body)
+        text = +""
+        body.each { text << _1 }
+        text
+      ensure
+        body.close if body.respond_to?(:close)
+      end
+
+      # The root cause's class, message and first frame, unfiltered (no
+      # backtrace cleaner), so the frame names the file and line to fix.
+      def self.describe_error(error)
+        root = error
+        root = root.cause while root.cause
+        [root.class.name, root.message, root.backtrace&.first]
+      end
+    end
+  end
+end

data/lib/conformance_kit/ractorize/runner.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative "../ractorize"
+require_relative "../audit"
+require_relative "request"
+
+module ConformanceKit
+  module Ractorize
+    # Runs in its own process (boot.rb): it boots the app, freezes it for good
+    # and leaves global state behind. Boots in production with
+    # `unshareable_proc_action = :raise`, calls `Rails.application.ractorize!`,
+    # serves each `ractorize.requests` path inside a non-main Ractor, then audits
+    # `ractorize.audit_namespaces` in the same process. Exits 0 when all of it
+    # passes or the run is skipped (with the reason), 1 otherwise.
+    class Runner
+      def initialize(config, out:)
+        @config = config
+        @out = out
+        @failures = 0
+      end
+
+      def run
+        reason = unavailable_reason
+        return skip(reason) if reason
+
+        ActiveSupport::Ractors.unshareable_proc_action = :raise
+        return 1 unless stage("boot") { boot }
+        return 1 unless stage("Rails.application.ractorize!") { ractorize }
+
+        serve_requests
+        audit
+        summary
+      end
+
+      private
+
+      def unavailable_reason
+        return rails_reason if Ractorize.available?
+
+        "Ractor#value is unavailable on #{RUBY_ENGINE} #{RUBY_VERSION} (needs Ruby 4.0)"
+      end
+
+      # Checked before :raise is armed, so a Rails without ractorize! skips instead of failing its boot.
+      def rails_reason
+        require "rails"
+        require "active_support/ractors"
+        return if Rails::Application.method_defined?(:ractorize!)
+
+        "Rails #{Rails.version} has no Rails.application.ractorize!: run it with BUNDLE_GEMFILE=Gemfile.ractorize"
+      rescue LoadError => e
+        return "Rails is not in the bundle: run it with BUNDLE_GEMFILE=Gemfile.ractorize" if e.path == "rails"
+
+        "ActiveSupport::Ractors is unavailable (Rails before 8.2): run it with BUNDLE_GEMFILE=Gemfile.ractorize"
+      end
+
+      def boot
+        ENV["RAILS_ENV"] = "production"
+        ENV["SECRET_KEY_BASE_DUMMY"] ||= "1"
+        environment = File.join(@config.ractorize_app, "config/environment.rb")
+        require environment
+        raise "#{environment} defined no Rails.application" unless defined?(::Rails) && ::Rails.application
+      end
+
+      def ractorize
+        Warning[:experimental] = false
+        Rails.application.ractorize!
+        require "i18n/ractorize"
+      rescue LoadError => e
+        raise unless e.path == "i18n/ractorize"
+
+        @out.puts "ractorize: note: i18n/ractorize is unavailable (released i18n): I18n reads fail in a Ractor"
+      end
+
+      def stage(name)
+        yield
+        @out.puts "ractorize: #{name}: ok"
+        true
+      rescue Exception => e # rubocop:disable Lint/RescueException -- the failure is the report
+        @out.puts "ractorize: #{name} failed: #{format(Request.describe_error(e))}"
+        false
+      end
+
+      def serve_requests
+        @config["ractorize.requests"].each do |path|
+          result = Request.serve(Rails.application, path)
+          failed = result[:error] || result[:status].nil? || result[:status] >= 500
+          @failures += 1 if failed
+          @out.puts "  GET #{path} -> #{describe(result)}"
+        end
+      end
+
+      def describe(result)
+        status = result[:status] ? "#{result[:status]} (#{result[:body].bytesize} bytes)" : "raised"
+        result[:error] ? "#{status}: #{format(result[:error])}" : status
+      end
+
+      def format((klass, message, frame)) = "#{klass}: #{message}\n      at #{frame}"
+
+      def audit
+        namespaces = @config.ractorize_namespaces
+        return @out.puts("ractorize: audit: nothing to audit (set ractorize.audit_namespaces)") if namespaces.empty?
+
+        missing = namespaces.reject { Object.const_defined?(_1) }
+        return audit_failed("namespace #{missing.join(', ')} is not defined after boot") if missing.any?
+
+        findings = Audit.new(namespaces: namespaces, allowlist: @config.allowlist,
+                             skip_autoloads: @config.skip_autoloads).findings
+        @failures += findings.size
+        @out.puts "ractorize: audit #{namespaces.join(', ')} after ractorize!: #{findings.size} findings"
+        findings.each { @out.puts "  #{_1}" }
+      end
+
+      def audit_failed(message)
+        @failures += 1
+        @out.puts "ractorize: audit failed: #{message}"
+      end
+
+      def summary
+        return 0.tap { @out.puts "ractorize passed" } if @failures.zero?
+
+        @out.puts "ractorize failed: #{@failures} failures (failed requests and audit findings)"
+        1
+      end
+
+      def skip(reason)
+        @out.puts "ractorize: skipped: #{reason}"
+        0
+      end
+    end
+  end
+end

data/lib/conformance_kit/ractorize.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ConformanceKit
+  # The ractorize job: boot a gem's test app the way Rails 8.2 runs it across
+  # Ractors (`Rails.application.ractorize!`), serve requests inside non-main
+  # Ractors and audit what they read. See README "The ractorize job".
+  module Ractorize
+    # Ractor#value is Ruby 4.0's; before it, results came back through #take.
+    def self.available? = defined?(::Ractor) && ::Ractor.method_defined?(:value)
+  end
+end

data/lib/conformance_kit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ConformanceKit
-  VERSION = "0.4.2"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: conformance-kit
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors:
 - mhenrixon
@@ -23,6 +23,7 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- config/ractorize.gemfile
 - config/rubocop.yml
 - config/rubocop_spinel.yml
 - exe/conformance-audit
@@ -40,8 +41,13 @@ files:
 - lib/conformance_kit/cli.rb
 - lib/conformance_kit/cli/check.rb
 - lib/conformance_kit/cli/doctor.rb
+- lib/conformance_kit/cli/ractorize_check.rb
 - lib/conformance_kit/config.rb
 - lib/conformance_kit/minitest.rb
+- lib/conformance_kit/ractorize.rb
+- lib/conformance_kit/ractorize/boot.rb
+- lib/conformance_kit/ractorize/request.rb
+- lib/conformance_kit/ractorize/runner.rb
 - lib/conformance_kit/result.rb
 - lib/conformance_kit/rspec.rb
 - lib/conformance_kit/shareability.rb