conformance-kit 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45e9d40d8ce04df0a8aae9f4f0bd8da57e2f0f649c2549f1649f7d9d5ed7adc2
-  data.tar.gz: df75fb6611c183f7d93d52f95755022f6154afd63cd60a541346e779107e317b
+  metadata.gz: 6e74bc1ed523498fd8aa7cd04191a6b13b690568c21a5a16627c0d2d147afb15
+  data.tar.gz: 9138ad7259e5f81442f50c9fab3e6a9b3fd08a3569a4861f27e62bc945f446b5
 SHA512:
-  metadata.gz: ea8d19b3ca7a5dfdb2a4cd5d5a9e12c350c105ffa7af381319f7d31efc5a10ae8e6e8c35b5ef2f8cb0e70f23f2dcdaa417e8bf96617c9ac51280d176d106272d
-  data.tar.gz: aea92dfbc96c976dd0a4a31d556d8d111764c31ddfa14dab32f7f5123aad84272ca59f4251302d160f635af1289de41a357fdae78f474db6ca16a3dc13d2f1e8
+  metadata.gz: acb89af04013c0b5e8efc69da423c53f794c9305359c0f7dfe131066cfa9f47f6436e586c6de74d80272a25a3f8f29deab16831045c37971d30815968b6286e0
+  data.tar.gz: 4ac36fc7dbef17b06b1c2fd7bca8c38ee6f915a910324f1173602af05d51ed571207c2f02536cd8d926adebe2d9e54a3c484dc606976d1bf199424860cedb209

data/CHANGELOG.md

@@ -1,6 +1,23 @@
 # Changelog
 
-## Unreleased
+## 0.3.0
+
+Breaking (pre-1.0): `conformance.yml` is a reusable workflow that each repo calls, instead of one an org ruleset requires. It runs on `workflow_call` only. A repo adds a caller pinned to a release tag (`uses: zoolutions/conformance-kit/.github/workflows/conformance.yml@vX.Y.Z`, see the README) and makes `conformance / Conformance settings` and `conformance / Conformance (Ruby 4.0)` required checks in its own branch ruleset. Repos outside zoolutions can use it the same way.
+
+- The version handshake reads `job.workflow_ref` (the called workflow's own tag) instead of `github.workflow_ref` (the caller's).
+- This repo calls its own workflow through `.github/workflows/conformance-self.yml`.
+
+## 0.2.0
+
+Breaking (pre-1.0): the reusable workflows `ractor.yml` and `probes.yml` are replaced by `conformance.yml`, which an org ruleset requires at a release tag. A repo opts in with `.conformance.yml`, `gem "conformance-kit", "~> 0.2"` and `gem "rubocop-thread_safety", ">= 0.8"` in its Gemfile, and `inherit_gem: { conformance-kit: config/rubocop.yml }` in `.rubocop.yml` (`conformance-kit doctor` checks all three); it needs no workflow edits.
+
+- `.conformance.yml` 0.2 schema: `audit:` (`require`, `namespace`, `strict_autoloads`, `skip_autoloads`), `ractor:` (`ruby`, `test_command`, `env`, `setup`, `working_directory`), `probes:` (`gem_name`, `paths`, `roundhouse_app`) and the unchanged `main_only:`. Every key is validated; an unknown key or a wrong type exits 2.
+- `conformance-kit` executable: `check` (doctor, `ractor.setup`, `ractor.test_command`, then `conformance-audit --strict`), `doctor [--expect X.Y]` and `config KEY`.
+- `conformance-audit` reads `audit.require` and `audit.namespace` when no flags are given (flags still override); `--config` is the new name for `--allowlist`.
+- `audit.strict_autoloads: true` makes `--strict` fail on unloaded autoloads not listed in `audit.skip_autoloads` (default `false`, 0.1's behaviour).
+- `.github/workflows/conformance.yml`: the Ruby 4.0 conformance job (with a `postgres:18` service and the version handshake from `github.workflow_ref`) and the report-only compiler probes.
+
+## 0.1.0
 
 - Shared examples (`require "conformance_kit/rspec"`): `"thread-safe under contention"`, `"fiber-safe under an Async reactor"`, `"a boot-finalized configuration"` and `"runs inside a non-main Ractor"` (Ruby 4.0+, tagged `:ractor`).
 - The same checks as Minitest assertions (`require "conformance_kit/minitest"`): `assert_thread_safe`, `assert_fiber_safe`, `assert_boot_finalized`, `assert_runs_in_ractor`.

data/README.md

@@ -6,8 +6,8 @@ Concurrency conformance for the zoolutions gems. A gem that adopts it is held to
 |---|---|---|
 | 1 thread-safe | no unguarded shared mutable state on the request/broadcast path | `config/rubocop.yml` (rubocop-thread_safety) + `"thread-safe under contention"` |
 | 2 fiber-safe | correct under a fiber scheduler (Falcon/Async): request state fiber-local, no `Thread.main[]` misuse | `"fiber-safe under an Async reactor"` |
-| 3 Ractor-clean | the gem adds no Ractor blocker beyond its dependencies': config shareable after boot, per-Ractor caches, no locks in constants | `"a boot-finalized configuration"`, `conformance-audit --strict`, the Ruby 4.0 `"runs inside a non-main Ractor"` canary (`ractor.yml`) |
-| 4 compiler-probed | Spinel/Roundhouse readiness is measured, never gated | `probes.yml` (report-only) |
+| 3 Ractor-clean | the gem adds no Ractor blocker beyond its dependencies': config shareable after boot, per-Ractor caches, no locks in constants | `"a boot-finalized configuration"`, `conformance-audit --strict`, the Ruby 4.0 `"runs inside a non-main Ractor"` canary (`conformance.yml`) |
+| 4 compiler-probed | Spinel/Roundhouse readiness is measured, never gated | the probes job of `conformance.yml` (report-only) |
 
 Background, the finalize-at-boot pattern and the settled decisions: [zoolutions/phlex-reactive#363](https://github.com/zoolutions/phlex-reactive/issues/363).
 
@@ -16,7 +16,7 @@ Background, the finalize-at-boot pattern and the settled decisions: [zoolutions/
 ```ruby
 # Gemfile
 group :development, :test do
-  gem "conformance-kit", github: "zoolutions/conformance-kit"
+  gem "conformance-kit", "~> 0.3", require: false
   gem "rubocop-thread_safety", ">= 0.8", require: false # for config/rubocop.yml
   gem "async", require: false                 # optional: runs the fiber example
 end
@@ -101,10 +101,11 @@ On Ruby 3.4+ this is `Ractor.store_if_absent` (atomic, one value per Ractor). Be
 ## `conformance-audit`
 
 ```bash
-bundle exec conformance-audit --require ./lib/my_gem --namespace MyGem --strict
+bundle exec conformance-audit --strict                                         # audit.require + audit.namespace from .conformance.yml
+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), 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, 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)
@@ -114,28 +115,48 @@ conformance-audit: 2 findings in MyGem (1 allowlisted main-only; 14 modules audi
 
 Limits, so a green run means what it says:
 
-- Unloaded autoload constants are skipped and listed, never loaded mid-walk: require (or eager-load) everything the audit should see. The header counts the modules audited and the autoloads skipped.
+- Unloaded autoload constants are skipped and listed, never loaded mid-walk: require (or eager-load) everything the audit should see. The header counts the modules audited and the autoloads skipped. With `audit.strict_autoloads: true`, `--strict` also fails on every skipped autoload not listed in `audit.skip_autoloads`, so a green run means every autoload not deliberately skipped was audited.
 - `private_constant`s are invisible to it (Ruby has no public way to enumerate them). `config/rubocop.yml` and the boot-finalized example are the gates for those.
 
 | Exit | Meaning |
 |---|---|
 | 0 | no unallowlisted findings; or findings without `--strict` (report only); or no `Ractor` on this engine |
-| 1 | unallowlisted findings under `--strict` |
-| 2 | usage error, a namespace that is not defined or not a module, a file that cannot be required, or an invalid allowlist |
+| 1 | unallowlisted findings under `--strict` (or, with `audit.strict_autoloads`, unlisted unloaded autoloads) |
+| 2 | usage error, no namespace from either the flags or `audit.namespace`, a namespace that is not defined or not a module, a file that cannot be required, or an invalid `.conformance.yml` |
 
 ### `.conformance.yml`
 
-State that is deliberately main-only, read from `.conformance.yml` in the working directory (or `--allowlist PATH`). Every entry needs a `reason:`; an entry without one is an error (exit 2).
+One file per repo says what it is held to. It is read from the working directory (or `--config PATH`; `--allowlist PATH` still works). `audit.require` and `ractor.working_directory` are relative to the file; `ractor.setup`, `ractor.test_command`, `probes.paths` and `probes.roundhouse_app` run in (or are relative to) `ractor.working_directory`. Every key is validated: an unknown key or a wrong type is an error (exit 2) naming the file and the key.
 
 ```yaml
+audit:
+  require: [./lib/my_gem, ./spec/support/eager_load.rb]   # files to require (list)
+  namespace: [MyGem]                                       # constants to audit (list)
+  strict_autoloads: true                                   # optional, default false
+  skip_autoloads:                                          # optional; each needs a reason
+    - name: MyGem::Optional
+      reason: only loads with pgbus present
+ractor:
+  ruby: "4.0"                                  # default "4.0" (quote it)
+  test_command: bundle exec rspec --tag ractor # default; Minitest gems set their own
+  env:                                         # optional string map, applied before setup/test_command
+    PGBUS_DATABASE_URL: postgres://postgres:postgres@localhost:5432/pgbus_test
+  setup: bin/conformance-db-setup              # optional command run once before test_command
+  working_directory: .                         # default "."
+probes:
+  gem_name: my_gem                             # required for the probes job
+  paths: [lib]                                 # default [lib]
+  roundhouse_app: spec/dummy                   # optional
 main_only:
-  - name: MyGem::Registry.@lock     # class/module ivar: Owner.@ivar
+  - name: MyGem::Registry.@lock                # class/module ivar: Owner.@ivar
     reason: guards boot-time registration; no non-main Ractor ever registers
-  - name: MyGem::LOCK               # constant: Owner::NAME
+  - name: MyGem::LOCK                          # constant: Owner::NAME
     reason: ...
 ```
 
-Entries inside the audited namespaces that no longer turn up are listed as stale.
+`main_only:` is state that is deliberately main-only: every entry needs a `reason:`. Entries inside the audited namespaces that no longer turn up are listed as stale, and so are `audit.skip_autoloads` entries that are no longer unloaded autoloads.
+
+`strict_autoloads: true` needs `audit.require` to load everything, e.g. a file that calls your Zeitwerk loader's `eager_load!`.
 
 ## RuboCop
 
@@ -149,47 +170,80 @@ Turns on the six `rubocop-thread_safety` cops (`ClassAndModuleAttributes`, `Clas
 
 `config/rubocop_spinel.yml` runs only `Spinel/Unsupported` (rubocop_spinel). It is for the report-only probe, never your lint: it flags `class << self`.
 
-## Reusable workflows
+## Enforcement
+
+Conformance runs as **one reusable workflow in this repo**, `.github/workflows/conformance.yml`. Any repo can call it, inside zoolutions or not. A repo opts in with
+
+1. `.conformance.yml` (above),
+2. the Gemfile lines (`conformance-kit ~> 0.3`, `rubocop-thread_safety >= 0.8`),
+3. `inherit_gem: { conformance-kit: config/rubocop.yml }` in `.rubocop.yml`,
+4. a caller, pinned to a release tag:
 
 ```yaml
-# .github/workflows/main.yml
+# .github/workflows/conformance.yml
+name: Conformance
+
+on:
+  pull_request:
+  merge_group:
+
+permissions:
+  contents: read
+
 jobs:
-  ractor:
-    uses: zoolutions/conformance-kit/.github/workflows/ractor.yml@main
-    with:
-      require: ./lib/my_gem
-      namespace: MyGem
+  conformance:
+    uses: zoolutions/conformance-kit/.github/workflows/conformance.yml@v0.3.0
+```
+
+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:
+
+- **Conformance settings** reads `ractor.ruby` and `ractor.working_directory`.
+- **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.
+
+### Staying current
+
+Dependabot bumps both pins: the `uses:` tag (`github-actions`) and the gem (`bundler`), in separate pull requests.
 
-  probes:
-    uses: zoolutions/conformance-kit/.github/workflows/probes.yml@main
-    with:
-      gem-name: my_gem
+```yaml
+# .github/dependabot.yml
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule: { interval: weekly }
+  - package-ecosystem: bundler
+    directory: /
+    schedule: { interval: weekly }
 ```
 
-**`ractor.yml`** (the Tier 3 gate): the Ractor examples, then `conformance-audit --strict`.
+Merge the gem bump first: after a minor or major release the workflow bump fails the version handshake until the lockfile has caught up.
 
-| Input | Default | |
-|---|---|---|
-| `require` | required | files the audit requires (space-separated) |
-| `namespace` | required | constants to audit (space-separated) |
-| `ruby-version` | `4.0` | |
-| `allowlist` | `.conformance.yml` | skipped when the default file is absent |
-| `test-command` | `bundle exec rspec --tag ractor` | Minitest gems pass their own |
-| `audit` | `true` | `false` runs only the examples |
-| `working-directory` | `.` | |
+### `conformance-kit check`, the local equivalent
+
+```bash
+bundle exec conformance-kit check    # doctor, ractor.setup, ractor.test_command, then conformance-audit --strict
+bundle exec conformance-kit doctor   # the static checks only
+bundle exec conformance-kit config probes.gem_name
+```
 
-**`probes.yml`** (Tier 4, report-only): `rubocop_spinel`, `spinel-compat probe <gem-name> --dir .` and, when `roundhouse-app` is set, `roundhouse check`. Every probe step continues on error; the reports go to the run summary and an artifact. It never fails a build.
+`check` stops at the first failing stage, names it, and exits with its status. Run it before adding the caller: what passes here passes the workflow (on the same Ruby).
 
-| Input | Default | |
-|---|---|---|
-| `gem-name` | required | the gem spinel-compat probes from the checkout |
-| `ruby-version` | `4.0` | |
-| `paths` | `lib` | what rubocop_spinel inspects (space-separated) |
-| `roundhouse-app` | `""` | a Rails app directory (e.g. `spec/dummy`); empty skips it |
-| `roundhouse-version` | `v2026.9.18` | the rubys/roundhouse release to install |
-| `roundhouse-sha256` | SHA-256 of that release's `roundhouse-x86_64-unknown-linux-musl.tar.xz` | checked before the binary runs; change it with `roundhouse-version` |
-| `artifact-name` | `conformance-probes` | |
-| `working-directory` | `.` | |
+`doctor` checks that `.conformance.yml` exists, is valid and sets `audit.namespace`; that `.rubocop.yml` inherits `conformance-kit: config/rubocop.yml`; and that `rubocop-thread_safety` resolves at `>= 0.8`. Each problem names its fix. `--expect X.Y` also checks the resolved `conformance-kit` is at least `X.Y`.
+
+`config KEY` prints a dotted key's value (a list joined with spaces, `ractor.env` as `NAME=value` lines, an unset key as an empty line); an unknown key exits 2.
+
+| Exit | Meaning |
+|---|---|
+| 0 | ok |
+| 1 | a check failed (`check` exits with the failing stage's status) |
+| 2 | usage error or an invalid `.conformance.yml` |
+
+### 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`. That a tag-pinned call carries the tag is GitHub's documented behaviour; it has not been seen on a run yet, since v0.3.0 is the first tag that can be called. Until it has, treat the handshake as pending validation.
 
 ## Development
 
@@ -197,4 +251,4 @@ jobs:
 bundle exec rake   # rspec + rubocop; CI runs Ruby 3.2, 3.4 and 4.0
 ```
 
-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`) and calls its own workflows in CI.
+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/rubocop_spinel.yml

@@ -1,5 +1,5 @@
 # conformance-kit's report-only Spinel probe (Tier 4): only the Spinel cops,
-# never a gate. Run by .github/workflows/probes.yml as
+# never a gate. Run by the probes job of .github/workflows/conformance.yml as
 #
 #   rubocop --config <conformance-kit>/config/rubocop_spinel.yml lib
 #

data/exe/conformance-kit

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/conformance_kit/cli"
+
+exit ConformanceKit::CLI.run(ARGV)

data/lib/conformance_kit/audit/allowlist.rb

@@ -14,6 +14,8 @@ module ConformanceKit
     #       reason: guards boot-time registration; never touched by a non-main Ractor
     #     - name: MyGem::LOCK                # a constant: Owner::NAME
     #       reason: ...
+    #
+    # `audit.skip_autoloads:` entries have the same shape (`key:` names the list).
     class Allowlist
       def self.empty = new([])
 
@@ -28,8 +30,9 @@ module ConformanceKit
 
       attr_reader :entries
 
-      def initialize(entries, source: "the allowlist")
-        raise AllowlistError, "#{source}: main_only: must be a list" unless entries.is_a?(Array)
+      def initialize(entries, source: "the allowlist", key: "main_only")
+        @key = key
+        raise AllowlistError, "#{source}: #{key}: must be a list" unless entries.is_a?(Array)
 
         @entries = entries.map { validate(_1, source) }
       end
@@ -43,14 +46,14 @@ module ConformanceKit
       def validate(entry, source)
         unless entry.is_a?(Hash)
           raise AllowlistError,
-                "#{source}: each main_only entry needs a name: and a reason:, got #{entry.inspect}"
+                "#{source}: each #{@key} entry needs a name: and a reason:, got #{entry.inspect}"
         end
 
         name = entry["name"]
-        raise AllowlistError, "#{source}: a main_only entry has no name: (#{entry.inspect})" if blank?(name)
+        raise AllowlistError, "#{source}: a #{@key} entry has no name: (#{entry.inspect})" if blank?(name)
         if blank?(entry["reason"])
           raise AllowlistError,
-                "#{source}: #{name} has no reason: (say why it is safe main-only)"
+                "#{source}: #{name} has no reason: (say why it is safe)"
         end
 
         entry

data/lib/conformance_kit/audit/cli.rb

@@ -4,12 +4,18 @@ require "optparse"
 
 module ConformanceKit
   class Audit
-    # `conformance-audit --require FILE --namespace CONST [--strict] [--allowlist PATH]`
+    # `conformance-audit [--require FILE] [--namespace CONST] [--strict] [--config PATH]`
+    #
+    # Reads `.conformance.yml` (or `--config PATH`, alias `--allowlist`): its
+    # `audit.require`/`audit.namespace` when no flags are given, its `main_only:`
+    # allowlist, and `audit.strict_autoloads`/`audit.skip_autoloads`.
     #
     # Exit codes: 0 clean (or report-only, or no Ractor on this engine),
-    # 1 unallowlisted findings under --strict, 2 usage or allowlist error.
+    # 1 unallowlisted findings (or, with strict_autoloads, unlisted unloaded
+    # autoloads) under --strict, 2 usage or config error.
     class CLI
-      DEFAULT_ALLOWLIST = ".conformance.yml"
+      DEFAULT_CONFIG = Config::DEFAULT_PATH
+      DEFAULT_ALLOWLIST = DEFAULT_CONFIG
       USAGE_ERROR = 2
 
       def self.run(argv, out: $stdout, err: $stderr) = new(out, err).run(argv)
@@ -23,51 +29,62 @@ module ConformanceKit
         options = parse(argv)
         return unavailable unless defined?(::Ractor)
 
-        options[:requires].each { require File.expand_path(_1) }
-        options[:namespaces].each { check_namespace(_1) }
-        audit = Audit.new(namespaces: options[:namespaces], allowlist: allowlist(options[:allowlist]))
-        report(audit, options[:strict])
-      rescue OptionParser::ParseError, AllowlistError, LoadError, NameError, ArgumentError => e
+        config = load_config(options[:config])
+        namespaces = options[:namespaces].empty? ? config["audit.namespace"] : options[:namespaces]
+        raise OptionParser::MissingArgument, NO_NAMESPACE if namespaces.empty?
+
+        requires(options, config).each { require _1 }
+        namespaces.each { check_namespace(_1) }
+        audit = Audit.new(namespaces: namespaces, allowlist: config.allowlist, skip_autoloads: config.skip_autoloads)
+        report(audit, options[:strict], config.strict_autoloads?)
+      rescue OptionParser::ParseError, ConfigError, AllowlistError, LoadError, NameError, ArgumentError => e
         @err.puts "conformance-audit: #{e.message}"
         USAGE_ERROR
       end
 
+      NO_NAMESPACE = "--namespace: nothing to audit (pass --namespace or set .conformance.yml audit.namespace)"
+      private_constant :NO_NAMESPACE
+
       private
 
       def parse(argv)
-        options = { requires: [], namespaces: [], strict: false, allowlist: nil }
+        options = { requires: [], namespaces: [], strict: false, config: nil }
         parser(options).parse!(argv.dup)
-        raise OptionParser::MissingArgument, "--namespace (the constant to audit)" if options[:namespaces].empty?
-
         options
       end
 
       def parser(options)
         OptionParser.new do |o|
-          o.banner = "Usage: conformance-audit --require FILE --namespace CONST [--strict] [--allowlist PATH]"
-          o.on("--require FILE", "Require FILE before auditing (repeatable)") { options[:requires] << _1 }
-          o.on("--namespace CONST", "Audit CONST and everything under it (repeatable)") do |name|
+          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|
+            options[:requires] << file
+          end
+          o.on("--namespace CONST", "Audit CONST and all under it (repeatable; default audit.namespace)") do |name|
             options[:namespaces] << name.delete_prefix("::")
           end
           o.on("--strict", "Exit 1 on any unallowlisted finding") { options[:strict] = true }
-          o.on("--allowlist PATH", "main_only: allowlist (default: #{DEFAULT_ALLOWLIST} if present)") do |path|
-            options[:allowlist] = path
+          o.on("--config PATH", "--allowlist PATH", "The config to read (default: #{DEFAULT_CONFIG})") do |path|
+            options[:config] = path
           end
         end
       end
 
-      def check_namespace(name)
-        value = Object.const_get(name)
-        raise ArgumentError, "--namespace #{name} is a #{value.class}, not a module" unless value.is_a?(Module)
+      def load_config(path)
+        raise ConfigError, "config #{path} does not exist" if path && !File.exist?(path)
+
+        Config.load(path || DEFAULT_CONFIG)
       end
 
-      def allowlist(path)
-        return Allowlist.load(path) if path
-        return Allowlist.load(DEFAULT_ALLOWLIST) if File.exist?(DEFAULT_ALLOWLIST)
+      def requires(options, config)
+        return config.audit_requires if options[:requires].empty?
+
+        options[:requires].map { File.expand_path(_1) }
+      end
 
-        Allowlist.empty
-      rescue Errno::ENOENT
-        raise AllowlistError, "allowlist #{path} does not exist"
+      def check_namespace(name)
+        name = name.delete_prefix("::")
+        value = Object.const_get(name)
+        raise ArgumentError, "namespace #{name} is a #{value.class}, not a module" unless value.is_a?(Module)
       end
 
       def unavailable
@@ -75,21 +92,40 @@ module ConformanceKit
         0
       end
 
-      def report(audit, strict)
+      def report(audit, strict, strict_autoloads)
         findings = audit.findings
-        allowlisted = audit.allowlisted
+        autoloads = strict_autoloads ? audit.unexpected_autoloads : []
+        header(audit, findings)
+        details(audit, strict_autoloads)
+        return 0 if findings.empty? && autoloads.empty?
+        return 1 if strict
+
+        @out.puts "report only: --strict fails on these"
+        0
+      end
+
+      def header(audit, findings)
         @out.puts "conformance-audit: #{findings.size} findings in #{audit.namespaces.join(', ')} " \
-                  "(#{allowlisted.size} allowlisted main-only; #{audit.modules_audited} modules audited, " \
+                  "(#{audit.allowlisted.size} allowlisted main-only; #{audit.modules_audited} modules audited, " \
                   "#{audit.skipped_autoloads.size} unloaded autoloads skipped)"
         findings.each { @out.puts "  #{_1}" }
-        section("allowlisted main-only:", allowlisted.map { "#{_1.name} — #{audit.allowlist.reason_for(_1.name)}" })
+      end
+
+      def details(audit, strict_autoloads)
+        allowlisted = audit.allowlisted.map { "#{_1.name} — #{audit.allowlist.reason_for(_1.name)}" }
+        section("allowlisted main-only:", allowlisted)
         section("stale allowlist entries (no longer found):", audit.stale)
-        section("unloaded autoloads, not audited (require or eager-load them):", audit.skipped_autoloads)
-        return 0 if findings.empty?
-        return 1 if strict
+        skipped = audit.skipped_autoloads - audit.unexpected_autoloads
+        section("unloaded autoloads skipped by audit.skip_autoloads:",
+                skipped.map { "#{_1} — #{audit.skip_autoloads.reason_for(_1)}" })
+        section("stale audit.skip_autoloads entries (no longer unloaded autoloads):", audit.stale_skip_autoloads)
+        section(autoload_title(strict_autoloads), audit.unexpected_autoloads)
+      end
 
-        @out.puts "report only: --strict fails on these"
-        0
+      def autoload_title(strict_autoloads)
+        return "unloaded autoloads, not audited (require or eager-load them):" unless strict_autoloads
+
+        "unloaded autoloads, not audited (strict_autoloads: eager-load them or list them in audit.skip_autoloads):"
       end
 
       def section(title, lines)

data/lib/conformance_kit/audit.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "conformance_kit"
+require_relative "config"
 require_relative "audit/allowlist"
 require_relative "audit/cli"
 
@@ -8,7 +9,8 @@ module ConformanceKit
   # Walks every loaded module under the given namespaces and reports each
   # constant and class/module instance variable whose value is not
   # Ractor-shareable. Unloaded autoload constants are skipped: require (or
-  # eager-load) everything the audit should see.
+  # eager-load) everything the audit should see, and list deliberate exceptions
+  # in `skip_autoloads` (`audit.skip_autoloads:` in .conformance.yml).
   class Audit
     Finding = Data.define(:name, :kind, :value_class, :path, :reason) do
       def to_s
@@ -17,11 +19,12 @@ module ConformanceKit
       end
     end
 
-    attr_reader :namespaces, :allowlist
+    attr_reader :namespaces, :allowlist, :skip_autoloads
 
-    def initialize(namespaces:, allowlist: Allowlist.empty)
+    def initialize(namespaces:, allowlist: Allowlist.empty, skip_autoloads: Allowlist.empty)
       @namespaces = namespaces
       @allowlist = allowlist
+      @skip_autoloads = skip_autoloads
     end
 
     def findings = partitioned.first
@@ -31,17 +34,26 @@ module ConformanceKit
 
     # Constants declared with `autoload` but never loaded: not audited.
     def skipped_autoloads
-      audited_modules.flat_map do |mod, name|
+      @skipped_autoloads ||= audited_modules.flat_map do |mod, name|
         constants_of(mod).select { autoload?(mod, _1) }.map { "#{name}::#{_1}" }
       end
     end
 
+    # Skipped autoloads not listed in skip_autoloads: what strict_autoloads fails on.
+    def unexpected_autoloads = skipped_autoloads - @skip_autoloads.names
+
     # Allowlisted names inside the audited namespaces that no longer turn up.
     def stale
       found = scan.map(&:name)
       @allowlist.names.select { in_namespace?(_1) && !found.include?(_1) }
     end
 
+    # skip_autoloads names inside the audited namespaces that are no longer unloaded autoloads.
+    def stale_skip_autoloads
+      skipped = skipped_autoloads
+      @skip_autoloads.names.select { in_namespace?(_1) && !skipped.include?(_1) }
+    end
+
     private
 
     def partitioned

data/lib/conformance_kit/cli/check.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "open3"
+require "rbconfig"
+
+module ConformanceKit
+  class CLI
+    # What the conformance workflow runs, and what a developer runs locally
+    # before flipping a repo: doctor, then ractor.setup and ractor.test_command
+    # (with ractor.env, in ractor.working_directory), then the strict audit.
+    # Stops at the first failing stage and exits with its status.
+    class Check
+      AUDIT = File.expand_path("../../../exe/conformance-audit", __dir__).freeze
+
+      def initialize(config, doctor, out:)
+        @config = config
+        @doctor = doctor
+        @out = out
+      end
+
+      def run
+        status = stages.each do |stage, command|
+          code = command.call
+          break failed(stage, code) unless code.zero?
+        end
+        return status if status.is_a?(Integer)
+
+        @out.puts "conformance-kit check passed"
+        0
+      end
+
+      private
+
+      def stages
+        list = [["doctor", -> { @doctor.run }]]
+        setup = @config["ractor.setup"]
+        list << ["ractor.setup", -> { shell(setup) }] if setup
+        list << ["ractor.test_command", -> { shell(@config["ractor.test_command"]) }]
+        list << ["audit", -> { audit }]
+      end
+
+      def shell(command)
+        @out.puts "==> #{command}"
+        @out.flush
+        exit_code(system(@config["ractor.env"], command, chdir: @config.working_directory))
+      end
+
+      def audit
+        @out.puts "==> conformance-audit --strict --config #{@config.source}"
+        output, status = Open3.capture2e(@config["ractor.env"], RbConfig.ruby, AUDIT, "--strict",
+                                         "--config", File.expand_path(@config.source), chdir: @config.root)
+        @out.print output
+        status.exitstatus || 1
+      end
+
+      # system returns nil when the command could not be spawned at all.
+      def exit_code(result)
+        return 127 if result.nil?
+
+        Process.last_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/doctor.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module ConformanceKit
+  class CLI
+    # The static checks the conformance workflow relies on. Every problem is
+    # listed with its fix; exit 1 when there is any.
+    class Doctor
+      THREAD_SAFETY = "rubocop-thread_safety"
+      THREAD_SAFETY_FLOOR = "0.8"
+      RUBOCOP_CONFIG = "config/rubocop.yml"
+
+      def initialize(config, out:, version:, specs:, expect: nil)
+        @config = config
+        @out = out
+        @version = Gem::Version.new(version)
+        @specs = specs
+        @expect = expect
+      end
+
+      def problems
+        [conformance_problem, rubocop_problem, thread_safety_problem, version_problem].compact
+      end
+
+      def run
+        found = problems
+        return report_ok if found.empty?
+
+        @out.puts "conformance-kit doctor: #{found.size} problem#{'s' unless found.size == 1}"
+        found.each { @out.puts "  - #{_1}" }
+        1
+      end
+
+      private
+
+      def report_ok
+        @out.puts "conformance-kit doctor: ok (conformance-kit #{@version}, #{@config.source})"
+        0
+      end
+
+      def conformance_problem
+        unless @config.exists?
+          return "no #{@config.source}: add one with audit.require and audit.namespace (see the conformance-kit README)"
+        end
+        return nil unless @config["audit.namespace"].empty?
+
+        "#{@config.source} sets no audit.namespace: list the constants to audit (e.g. audit.namespace: [MyGem])"
+      end
+
+      def rubocop_problem
+        path = File.join(@config.root, ".rubocop.yml")
+        fix = "add `inherit_gem: { conformance-kit: #{RUBOCOP_CONFIG} }`"
+        return "no #{path}: #{fix}" unless File.exist?(path)
+        return nil if inherits_kit?(YAML.safe_load_file(path, aliases: true))
+
+        "#{path} does not inherit conformance-kit's RuboCop config: #{fix}"
+      rescue Psych::Exception => e
+        "#{path} is not valid YAML (#{e.message})"
+      end
+
+      def inherits_kit?(rubocop)
+        gems = rubocop.is_a?(Hash) && rubocop["inherit_gem"]
+        gems.is_a?(Hash) && Array(gems["conformance-kit"]).include?(RUBOCOP_CONFIG)
+      end
+
+      def thread_safety_problem
+        spec = @specs[THREAD_SAFETY]
+        line = %(gem "#{THREAD_SAFETY}", ">= #{THREAD_SAFETY_FLOOR}", require: false)
+        return "#{THREAD_SAFETY} is not in the bundle: add `#{line}` to the Gemfile" unless spec
+        return nil if spec.version >= Gem::Version.new(THREAD_SAFETY_FLOOR)
+
+        "#{THREAD_SAFETY} #{spec.version} is resolved: bump it to >= #{THREAD_SAFETY_FLOOR} (`#{line}`)"
+      end
+
+      def version_problem
+        return nil if @expect.nil? || @version >= @expect
+
+        segments = @expect.segments.first(2).join(".")
+        "conformance-kit #{@version} is resolved, the workflow expects >= #{@expect}: " \
+          "bump conformance-kit to ~> #{segments} in the Gemfile and run bundle update conformance-kit"
+      end
+    end
+  end
+end

data/lib/conformance_kit/cli.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "conformance_kit"
+require_relative "config"
+require_relative "cli/doctor"
+require_relative "cli/check"
+
+module ConformanceKit
+  # `conformance-kit check|doctor|config KEY [--config PATH] [--expect X.Y]`
+  #
+  # Exit codes: 0 ok, 1 a check failed (`check` passes on its failing stage's
+  # status), 2 usage or config error.
+  class CLI
+    USAGE = <<~TEXT
+      Usage: conformance-kit COMMAND [--config PATH]
+        check [--expect X.Y]   doctor, ractor.setup, ractor.test_command, then conformance-audit --strict
+        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
+    USAGE_ERROR = 2
+
+    def self.run(argv, out: $stdout, err: $stderr, version: VERSION, specs: Gem.loaded_specs)
+      new(out: out, err: err, version: version, specs: specs).run(argv)
+    end
+
+    def initialize(out:, err:, version:, specs:)
+      @out = out
+      @err = err
+      @version = version
+      @specs = specs
+    end
+
+    def run(argv)
+      command, *rest = argv
+      options = parse(rest)
+      dispatch(command, options)
+    rescue OptionParser::ParseError, ConfigError, ArgumentError => e
+      @err.puts "conformance-kit: #{e.message}"
+      @err.puts USAGE
+      USAGE_ERROR
+    end
+
+    private
+
+    def dispatch(command, options)
+      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
+      else raise ArgumentError, command ? "unknown command #{command}" : "no command"
+      end
+    end
+
+    def parse(argv)
+      options = { config: Config::DEFAULT_PATH, expect: nil }
+      options[:args] = OptionParser.new do |o|
+        o.on("--config PATH") { options[:config] = _1 }
+        o.on("--expect X.Y") { options[:expect] = expected_version(_1) }
+      end.parse(argv)
+      options
+    end
+
+    def expected_version(value)
+      raise ArgumentError, "--expect #{value}: expected a version like 0.2" unless Gem::Version.correct?(value)
+
+      Gem::Version.new(value)
+    end
+
+    def config(options) = Config.load(options[:config])
+
+    def doctor(options)
+      Doctor.new(config(options), out: @out, version: @version, specs: @specs, expect: options[:expect])
+    end
+
+    def print_value(options)
+      key, *extra = options[:args]
+      raise ArgumentError, "config needs a KEY (e.g. probes.gem_name)" unless key
+      raise ArgumentError, "config takes one KEY, got also: #{extra.join(' ')}" if extra.any?
+
+      @out.puts format_value(config(options)[key])
+      0
+    end
+
+    def format_value(value)
+      case value
+      when Hash then value.map { |name, env_value| "#{name}=#{env_value}" }.join("\n")
+      when Array then value.map { _1.is_a?(Hash) ? _1["name"] : _1 }.join(" ")
+      else value.to_s
+      end
+    end
+  end
+end

data/lib/conformance_kit/config.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "audit/allowlist"
+
+module ConformanceKit
+  class ConfigError < StandardError; end
+
+  # A repo's `.conformance.yml`: what `conformance-kit check` and
+  # `conformance-audit` hold it to. Every key is validated; a missing file is
+  # an empty config. Paths in it are relative to the file.
+  #
+  #   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 }
+  #   main_only: []
+  class Config
+    DEFAULT_PATH = ".conformance.yml"
+
+    TYPES = {
+      "audit.require" => :list,
+      "audit.namespace" => :list,
+      "audit.strict_autoloads" => :boolean,
+      "audit.skip_autoloads" => :entries,
+      "ractor.ruby" => :string,
+      "ractor.test_command" => :string,
+      "ractor.env" => :string_map,
+      "ractor.setup" => :string,
+      "ractor.working_directory" => :string,
+      "probes.gem_name" => :string,
+      "probes.paths" => :list,
+      "probes.roundhouse_app" => :string,
+      "main_only" => :entries
+    }.freeze
+
+    DEFAULTS = {
+      "audit.require" => [].freeze,
+      "audit.namespace" => [].freeze,
+      "audit.strict_autoloads" => false,
+      "audit.skip_autoloads" => [].freeze,
+      "ractor.ruby" => "4.0",
+      "ractor.test_command" => "bundle exec rspec --tag ractor",
+      "ractor.env" => {}.freeze,
+      "ractor.working_directory" => ".",
+      "probes.paths" => ["lib"].freeze,
+      "main_only" => [].freeze
+    }.freeze
+
+    SECTIONS = %w[audit ractor probes].freeze
+
+    def self.load(path = DEFAULT_PATH)
+      root = File.dirname(File.expand_path(path))
+      return new({}, source: path, root: root, exists: false) unless File.exist?(path)
+
+      data = YAML.safe_load_file(path)
+      new(data.nil? ? {} : data, source: path, root: root, exists: true)
+    rescue Psych::Exception, SystemCallError => e
+      raise ConfigError, "#{path}: #{e.message}"
+    end
+
+    attr_reader :source, :root, :allowlist, :skip_autoloads
+
+    def initialize(data, source:, root:, exists: true)
+      @source = source
+      @root = root
+      @exists = exists
+      raise ConfigError, "#{source}: expected a mapping (audit:, ractor:, probes:, main_only:)" unless data.is_a?(Hash)
+
+      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.
+      @values = pairs.to_h.compact.to_h { |key, value| [key, normalize(key, validate(key, value))] }
+      @allowlist = entries("main_only")
+      @skip_autoloads = entries("audit.skip_autoloads")
+    end
+
+    def exists? = @exists
+
+    # A dotted key (`ractor.ruby`): its value, or its default (nil when it has none).
+    def [](key)
+      unknown_key!(key, TYPES.keys) unless TYPES.key?(key)
+
+      @values.fetch(key) { DEFAULTS[key] }
+    end
+
+    def audit_requires = self["audit.require"].map { File.expand_path(_1, root) }
+    def strict_autoloads? = self["audit.strict_autoloads"]
+    def working_directory = File.expand_path(self["ractor.working_directory"], root)
+
+    private
+
+    def flatten(data)
+      data.flat_map do |key, value|
+        next [[key, value]] if key == "main_only"
+
+        unknown_key!(key, [*SECTIONS, "main_only"]) unless SECTIONS.include?(key)
+        next [] if value.nil?
+        raise ConfigError, "#{source}: #{key}: must be a mapping, got #{value.class}" unless value.is_a?(Hash)
+
+        value.map { |sub, sub_value| ["#{key}.#{sub}", sub_value] }
+      end
+    end
+
+    # 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
+    end
+
+    def validate(key, value)
+      type = TYPES.fetch(key)
+      return value if valid?(type, value)
+
+      raise ConfigError, "#{source}: #{key} must be #{EXPECTED.fetch(type)}, got #{value.class} #{value.inspect}"
+    end
+
+    EXPECTED = {
+      list: "a list of strings",
+      string: "a string (quote it)",
+      boolean: "true or false",
+      string_map: "a mapping of names to string values (quote numbers)",
+      entries: "a list of name:/reason: entries"
+    }.freeze
+    private_constant :EXPECTED
+
+    def valid?(type, value)
+      case type
+      when :list then value.is_a?(Array) && value.all?(String)
+      when :string then value.is_a?(String)
+      when :boolean then [true, false].include?(value)
+      when :string_map then value.is_a?(Hash) && value.all? { |k, v| k.is_a?(String) && v.is_a?(String) }
+      when :entries then value.is_a?(Array)
+      end
+    end
+
+    def unknown_key!(key, known)
+      raise ConfigError, "#{source}: unknown key #{key} (one of #{known.join(', ')})"
+    end
+
+    def entries(key)
+      Audit::Allowlist.new(self[key], source: source, key: key)
+    rescue Audit::AllowlistError => e
+      raise ConfigError, e.message
+    end
+  end
+end

data/lib/conformance_kit/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: conformance-kit
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - mhenrixon
@@ -10,12 +10,13 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: Shared RSpec examples, a per-Ractor storage shim, a class-state audit,
-  RuboCop configs and reusable CI workflows that hold a gem to explicit thread-safe,
+  RuboCop configs and a reusable CI workflow that hold a gem to explicit thread-safe,
   fiber-safe and Ractor-clean tiers.
 email:
 - mikael@mhenrixon.com
 executables:
 - conformance-audit
+- conformance-kit
 extensions: []
 extra_rdoc_files: []
 files:
@@ -25,6 +26,7 @@ files:
 - config/rubocop.yml
 - config/rubocop_spinel.yml
 - exe/conformance-audit
+- exe/conformance-kit
 - lib/conformance_kit.rb
 - lib/conformance_kit/audit.rb
 - lib/conformance_kit/audit/allowlist.rb
@@ -34,6 +36,10 @@ files:
 - lib/conformance_kit/checks/fiber_reactor.rb
 - lib/conformance_kit/checks/ractor_canary.rb
 - lib/conformance_kit/checks/thread_contention.rb
+- lib/conformance_kit/cli.rb
+- lib/conformance_kit/cli/check.rb
+- lib/conformance_kit/cli/doctor.rb
+- lib/conformance_kit/config.rb
 - lib/conformance_kit/minitest.rb
 - lib/conformance_kit/result.rb
 - lib/conformance_kit/rspec.rb
@@ -61,7 +67,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.19
+rubygems_version: 3.6.9
 specification_version: 4
 summary: 'Concurrency conformance gates for Ruby gems: threads, fibers, Ractors and
   compiler probes.'