rigortype 0.4.6 → 0.4.7

data/lib/rigor/cli.rb

@@ -10,6 +10,9 @@ require_relative "version"
 require_relative "analysis/diagnostic"
 require_relative "analysis/result"
 require_relative "cli/options"
+require "did_you_mean"
+
+require_relative "cli/catalogue"
 require_relative "cli/diagnostic_formats"
 require_relative "ci_detector"
 require_relative "analysis/check_rules/rule_ids"
@@ -46,6 +49,17 @@ module Rigor
     # 2026-07-17 and nothing noticed. See `docs/internal-spec/config.md`.
     CONFIG_SCHEMA_URL = "https://github.com/rigortype/rigor/raw/master/schemas/rigor-config.schema.json"
 
+    # The comment `rigor init` writes under `plugins: []` when Gemfile.lock names a gem a bundled plugin models. The
+    # plugins are suggested, not enabled: ADR-96 Criterion 2 keeps a lockfile's presence from opting a project into a
+    # plugin's code, so the user uncomments the ones they want (#2536).
+    DETECTED_PLUGINS_HEADER = [
+      "# Detected from Gemfile.lock (suggested, not enabled). To load them, delete the `[]` above, uncomment the",
+      "# entries you want, then run `rigor plugins --strict`."
+    ].freeze
+
+    # The file whose presence marks a Rails application for `rigor init`'s `paths:` suggestion (#2560).
+    RAILS_APPLICATION_FILE = "config/application.rb"
+
     HANDLERS = {
       "check" => :run_check,
       "init" => :run_init,
@@ -79,6 +93,26 @@ module Rigor
       new(argv.dup, out: out, err: err).run
     end
 
+    # The parser `rigor init` parses with, built without parsing anything (the catalogue reads it, ADR-126 WD3).
+    def self.init_option_parser(options = {})
+      OptionParser.new do |opts|
+        opts.banner = "Usage: rigor init [options]"
+        opts.on("--force", "Overwrite an existing configuration file") { options[:force] = true }
+        opts.on("--path=PATH", "Configuration file path") { |value| options[:path] = value }
+        opts.on("--no-plugins", "Write no commented plugin suggestions from Gemfile.lock") do
+          options[:plugins] = false
+        end
+      end
+    end
+
+    # The parser `rigor help` parses with, built without parsing anything (the catalogue reads it, ADR-126 WD3).
+    def self.help_option_parser(options = {})
+      OptionParser.new do |opts|
+        opts.banner = "Usage: rigor help [--format=text|json] [<command>]"
+        Options.add_format(opts, options, "Output format: text (default) or json")
+      end
+    end
+
     def initialize(argv = ARGV.dup, out: $stdout, err: $stderr)
       @argv = argv
       @out = out
@@ -89,12 +123,14 @@ module Rigor
       command = @argv.shift
 
       case command
-      when nil, "help", "-h", "--help"
+      when nil, "-h", "--help"
         @out.puts(help)
         0
+      when "help"
+        run_help
       when "version", "-v", "--version"
-        @out.puts("rigor #{Rigor::VERSION}")
-        0
+        run_version
+
       else
         dispatch(command)
       end
@@ -139,6 +175,8 @@ module Rigor
       return arm_jit_deadline { send(handler) } if handler
 
       @err.puts("Unknown command: #{command}")
+      nearest = ::DidYouMean::SpellChecker.new(dictionary: Catalogue.names).correct(command).first
+      @err.puts("Did you mean `rigor #{nearest}`?") if nearest
       @err.puts(help)
       EXIT_USAGE
     end
@@ -156,6 +194,16 @@ module Rigor
       yield
     end
 
+    # `rigor version` and `-v`/`--version` print the version; `rigor version --help` prints the usage instead.
+    def run_version
+      if @argv.intersect?(%w[-h --help])
+        @out.puts("Usage: rigor version")
+      else
+        @out.puts("rigor #{Rigor::VERSION}")
+      end
+      0
+    end
+
     def run_check
       require_relative "cli/check_command"
 
@@ -168,15 +216,11 @@ module Rigor
       # present; no implicit merge).
       options = {
         force: false,
-        path: ".rigor.dist.yml"
+        path: ".rigor.dist.yml",
+        plugins: true
       }
 
-      parser = OptionParser.new do |opts|
-        opts.banner = "Usage: rigor init [options]"
-        opts.on("--force", "Overwrite an existing configuration file") { options[:force] = true }
-        opts.on("--path=PATH", "Configuration file path") { |value| options[:path] = value }
-      end
-      parser.parse!(@argv)
+      self.class.init_option_parser(options).parse!(@argv)
 
       path = options.fetch(:path)
       if File.exist?(path) && !options.fetch(:force)
@@ -184,24 +228,57 @@ module Rigor
         return 1
       end
 
-      File.write(path, init_template(path))
+      plugins = options.fetch(:plugins) ? detected_plugins : []
+      paths_suggestion = detected_paths
+      begin
+        File.write(path, init_template(path, plugins: plugins, paths_suggestion: paths_suggestion))
+      rescue SystemCallError => e
+        # A destination whose directory is missing or not writable is a bad path argument, the same usage error
+        # `--config=PATH` gives for a file that does not exist (exit 64, docs/manual/02-cli-reference.md). The bare
+        # Errno::ENOENT backtrace read as an internal crash.
+        reason = e.message.sub(/ @ .*\z/m, "")
+        @err.puts("rigor init: cannot write #{path}: #{reason}")
+        return EXIT_USAGE
+      end
       @out.puts("Created #{path}")
-      print_init_next_steps(path)
+      print_init_next_steps(path, plugins, paths_suggestion)
       0
     end
 
-    # `rigor init`'s template ships empty `plugins:` so a fresh init has nothing to validate — but the moment the user
-    # adds any plugin entry, the activation-failure surfaces enumerated in `rigor plugins`'s docstring become real.
+    # The bundled plugins whose target gems the project's `Gemfile.lock` declares: the read `rigor doctor` makes,
+    # through {PluginGapAdvisory}, so the two cannot disagree about what the project depends on. Empty without a
+    # lockfile, which leaves the template as it was before detection existed. The advisory is required lazily:
+    # it loads every bundled plugin's entry file, a cost a plain `rigor init` in a directory with no lockfile never
+    # pays.
+    def detected_plugins
+      require_relative "plugin_gap_advisory"
+
+      PluginGapAdvisory.gaps(project_root: Dir.pwd, plugins: []).map(&:plugin_gem)
+    end
+
+    # `rigor init`'s template lists the plugins Gemfile.lock detected, or ships empty `plugins:` so a fresh init has
+    # nothing to validate — but the moment the user adds any plugin entry, the activation-failure surfaces enumerated
+    # in `rigor plugins`'s docstring become real.
     # Point them at the verification command + the canonical readiness flow so silent failures (the cwd / Gemfile /
     # signature_paths mismatches that surfaced during the Mastodon trial) get caught the first time the user wires a
     # plugin, not the first time `rigor check` reports false positives that should have been covered.
-    def print_init_next_steps(path)
+    def print_init_next_steps(path, plugins = [], paths_suggestion = nil)
       @out.puts ""
       @out.puts "Next steps:"
-      @out.puts "  1. Edit #{path} — add the `plugins:` your project needs."
+      if plugins.empty?
+        @out.puts "  1. Edit #{path} — add the `plugins:` your project needs."
+      else
+        @out.puts "  1. Edit #{path} — to load a detected plugin, delete the `[]` on the `plugins:` line and"
+        @out.puts "     uncomment the entries you want:"
+        plugins.each { |gem| @out.puts "       #{gem}" }
+      end
       @out.puts "  2. Run `rigor plugins` to verify every configured plugin loads."
       @out.puts "     (`--strict` exits 1 on failure; ideal CI gate.)"
       @out.puts "  3. Run `rigor check` to analyse your code."
+      return if paths_suggestion.nil?
+
+      @out.puts "     `rigor check` analyses only `lib` until you edit `paths:` in #{path}. " \
+                "The suggestion is commented beneath it."
     end
 
     # Word-wraps `CheckRules::ALL_RULES` into a comma-separated, `#`-commented block for `init_template`, so the
@@ -230,8 +307,9 @@ module Rigor
 
     # Renders the starter `.rigor.yml` body. The template serialises `Configuration::DEFAULTS` (so the on-disk file
     # round-trips through `Configuration.load`) and prepends a short header that points the user at the keys they are
-    # most likely to want to edit.
-    def init_template(path = ".rigor.dist.yml")
+    # most likely to want to edit. `plugins:` stays the empty list the defaults ship; detected gems appear beneath it as
+    # comments, so a project with no lockfile gets the template it always did.
+    def init_template(path = ".rigor.dist.yml", plugins: [], paths_suggestion: nil)
       <<~YAML
         # yaml-language-server: $schema=#{CONFIG_SCHEMA_URL}
         # Rigor configuration. The full key reference is
@@ -287,10 +365,49 @@ module Rigor
         # `target_ruby` is left commented: the default only picks the syntax Rigor parses. Set it to the lowest
         # Ruby your project runs on, and Rigor also reports what that Ruby deprecates.
         # target_ruby: #{Configuration::DEFAULTS.fetch('target_ruby').dump}
-        #{YAML.dump(init_settings(path)).sub(/\A---\n/, '')}
+        #{settings_yaml(path, plugins, paths_suggestion)}
       YAML
     end
 
+    # The serialised settings. `plugins: []` stays valid YAML and schema-clean; when `Gemfile.lock` named a modelled
+    # gem, the suggestion block sits under it as comments, so nothing loads until the user uncomments a line. The
+    # `paths:` suggestion sits under the active `paths:` list the same way, and the active list stays `lib`.
+    def settings_yaml(path, plugins, paths_suggestion = nil)
+      yaml = YAML.dump(init_settings(path)).sub(/\A---\n/, "")
+      yaml = yaml.sub(/^plugins: \[\]\n/) { "plugins: []\n#{detected_plugins_block(plugins)}" } unless plugins.empty?
+      return yaml if paths_suggestion.nil?
+
+      yaml.sub(/^paths:\n(?:- .*\n)+/) { |active| active + paths_suggestion_block(paths_suggestion, path) }
+    end
+
+    # The commented `paths:` suggestion: one line naming what was detected and why, then the value to uncomment, written
+    # relative to the config file's directory like the active list (#1399).
+    def paths_suggestion_block(suggestion, path)
+      named = suggestion.fetch(:dirs).join(", ")
+      written = roots_relative_to(suggestion.fetch(:dirs), config_dir_of(path)).join(", ")
+      pronoun = suggestion.fetch(:dirs).one? ? "it" : "them"
+      "# #{suggestion.fetch(:reason)}: #{named}. To scan #{pronoun}, delete the `paths:` list above and " \
+        "uncomment the line below:\n# paths: [#{written}]\n"
+    end
+
+    # The source directories `rigor init` suggests for `paths:`, read from the project root (the cwd, like the plugin
+    # detection). A Rails application (config/application.rb) has app/ and lib/, each listed only if it exists. Any
+    # other layout gets no suggestion: the template's `lib` already covers it, and no other directory is guessed
+    # (#2560). Nil when there is nothing to add to today's `paths: [lib]`.
+    def detected_paths
+      return nil unless File.file?(RAILS_APPLICATION_FILE)
+
+      dirs = %w[app lib].select { |dir| File.directory?(dir) }
+      return nil if dirs.empty? || dirs == ["lib"]
+
+      { dirs: dirs, reason: "Detected a Rails app (#{RAILS_APPLICATION_FILE})" }
+    end
+
+    def detected_plugins_block(plugins)
+      lines = DETECTED_PLUGINS_HEADER + plugins.map { |gem| "#   - #{gem}" }
+      lines.map { |line| "#{line}\n" }.join
+    end
+
     # The settings `rigor init` writes: the defaults, with `test_paths:` spelled out as the test roots found now, so
     # the project's config says where its tests are rather than leaving it to auto-detection. The roots are written
     # relative to the config file's directory, which is what {Configuration.load} resolves them against. `paths:`
@@ -320,7 +437,7 @@ module Rigor
 
     # Each root is resolved against the physical cwd (where `rigor` reads it from), then written relative to the config
     # dir. With the config at the project root, both sides are the same physical directory, so the roots come out as
-    # they are spelled from it (`lib`, `spec`), which is master's output for the default config.
+    # they are spelled from it (`lib`, `spec`).
     def roots_relative_to(roots, config_dir)
       roots.map { |root| Pathname(File.absolute_path(root)).relative_path_from(config_dir).to_s }
     end
@@ -445,11 +562,18 @@ module Rigor
     # Surfaced because a bare `rigor describe` is the intuitive guess (the onboarding field trial saw it tried and met
     # "Unknown command").
     def run_describe
+      return print_describe_usage if @argv.intersect?(%w[-h --help])
+
       require_relative "cli/skill_command"
 
       CLI::SkillCommand.new(argv: ["describe", *@argv], out: @out, err: @err).run
     end
 
+    def print_describe_usage
+      @out.puts("Usage: rigor describe [--deep]")
+      0
+    end
+
     def run_docs
       require_relative "cli/docs_command"
 
@@ -480,41 +604,72 @@ module Rigor
       CLI::UpgradeCommand.new(argv: @argv, out: @out, err: @err).run
     end
 
+    # The text help is rendered from {Catalogue}, so the command list cannot drift from the dispatch table.
     def help
-      <<~HELP
-        Usage: rigor <command> [options]
-
-        Commands:
-          check      Analyze Ruby source files
-          init       Create a starter .rigor.yml
-          annotate   Print FILE with each line's last-expression type
-          type-of    Print inferred types at FILE:LINE[:COL] positions
-          lens       Map a file's declarations with their types and provenance (experimental)
-          trace      Replay how the engine typed FILE as a terminal animation
-          type-scan  Report Scope#type_of coverage across PATHs
-          effects    Report each method's effect labels, and the committed effect snapshot
-                     (opt-in; effects update/check/diff/explain)
-          explain    Print the description of one or all CheckRules
-          diff       Compare current diagnostics to a saved baseline JSON
-          baseline   Manage the baseline file (baseline generate/regenerate/dump/drift/prune)
-          sig-gen    Emit RBS skeletons inferred from .rb sources
-          lsp        Run the Rigor Language Server (LSP) over stdio
-          mcp        Run the Rigor MCP server over stdio
-          triage     Summarise diagnostics: distribution, hotspots, hints
-          coverage   Report type-precision coverage (precise vs Dynamic ratio)
-          unused     Report unreferenced classes, modules and constants as removal candidates
-          plugins    Report activation status of every configured plugin
-          plugin     Browse bundled plugin source as worked examples (list/path/print/root)
-          playground Start the browser playground (requires rigor-playground gem)
-          describe   Recommend the next skill for this project (alias for `skill describe`)
-          skill      Recommend the next skill + list/print bundled Agent Skills (skill describe, skill <name>)
-          docs       Print the bundled docs offline (docs <name>, docs --list)
-          show-bleedingedge  Show the bleeding-edge overlay + what your config adopts
-          doctor     Classify setup problems vs clean run with routed next actions
-          upgrade    Migration command skeleton (queued)
-          version    Print the Rigor version
-          help       Print this help
-      HELP
+      Catalogue.help_text
+    end
+
+    # `rigor help [--format=text|json] [<command>]`. `help <command>` behaves as `rigor <command> --help`;
+    # `--format=json` prints the whole {Catalogue} document.
+    def run_help
+      return print_command_list if @argv.intersect?(%w[-h --help])
+
+      options = parse_help_options
+      topics = @argv
+      return run_help_json(topics) if options[:format] == "json"
+
+      topic = topics.first
+      return run_help_topic(topic, topics.drop(1)) if topic
+
+      print_command_list
+    end
+
+    def print_command_list
+      @out.puts(help)
+      0
+    end
+
+    def parse_help_options
+      options = Hash.new("text")
+      # `order!` stops at the first positional, so the flags of the command being asked about are never parsed here.
+      self.class.help_option_parser(options).order!(@argv)
+      options
+    end
+
+    def run_help_json(topics)
+      if topics.any?
+        @err.puts("rigor help --format=json takes no command; it prints every command")
+        return EXIT_USAGE
+      end
+
+      @out.puts(JSON.pretty_generate(Catalogue.document))
+      0
+    end
+
+    def run_help_topic(topic, rest)
+      # Flags after the command name (`help type-of --workers=2`) are not parsed; a second word is not a subcommand's
+      # help, so it is refused rather than answered with the parent's.
+      extra = rest.reject { |word| word.start_with?("-") }
+      unless extra.empty?
+        @err.puts("rigor help takes one command, got: #{[topic, *extra].join(' ')}")
+        return EXIT_USAGE
+      end
+
+      case topic
+      when "help"
+        @out.puts(self.class.help_option_parser.help)
+        0
+      when "version"
+        @out.puts("Usage: rigor version")
+        0
+      when *HANDLERS.keys
+        @argv = ["--help"]
+        dispatch(topic)
+      else
+        @err.puts("Unknown command: #{topic}")
+        @err.puts(help)
+        EXIT_USAGE
+      end
     end
   end
 end

data/lib/rigor/config_audit.rb

@@ -35,7 +35,7 @@ module Rigor
   # (`rbs_extended.*`, `rbs.*`, `dynamic.*`) is left alone, since the engine emits those ids
   # outside the catalogue.
   module ConfigAudit
-    # One config-level finding. `kind` discriminates the source key (`:signature_path`,
+    # One config-level finding. `kind` discriminates the source key (`:unknown_key`, `:signature_path`,
     # `:bundled_plugin_signature_path`, `:library`, `:disabled_rule`, `:severity_override`,
     # `:bundler_bundle_path`, `:bundler_lockfile`, `:rbs_collection_lockfile`); `fields` carries the kind-specific
     # structured data merged into {#to_h} for JSON consumers.

data/lib/rigor/configuration/severity_profile.rb

@@ -15,12 +15,12 @@ module Rigor
     #   rules `:warning`.
     # - `strict`: Every rule is `:error`. CI-friendly.
     #
-    # The profile resolution order:
+    # The resolution order, first match wins:
     #
-    # 1. Profile-specific entry for the canonical rule id.
-    # 2. The diagnostic's own authored severity (the rule's default).
-    # 3. `:error` (catch-all so an unrecognised rule still emits visibly — the public-API drift spec catches
-    #    the bookkeeping gap separately).
+    # 1. An explicit `severity_overrides:` entry for the row (`resolve`'s `overrides:`).
+    # 2. A bleeding-edge severity override.
+    # 3. The profile's entry for the canonical rule id.
+    # 4. The diagnostic's own authored severity (the rule's default); an unrecognised rule keeps it.
     module SeverityProfile
       VALID_PROFILES = %i[lenient balanced strict].freeze
       VALID_SEVERITIES = %i[error warning info off].freeze

data/lib/rigor/configuration.rb

@@ -62,6 +62,10 @@ module Rigor
       "disable" => [],
       "libraries" => [],
       "signature_paths" => nil,
+      # Issue #2517 — a core signature directory loaded IN PLACE OF the `rbs` gem's `core/` (a provider such as
+      # rbs-shifter writes one for an older CRuby). `nil` (the default) loads the gem's core. Unlike
+      # `signature_paths:`, which only adds, this replaces: the default core is not loaded beside it.
+      "core_root" => nil,
       # The project's test roots: the directories (or files) holding its tests. `nil` (the default) auto-detects
       # whichever of `spec/` and `test/` exist, the same way `signature_paths: nil` auto-detects `sig/`; `[]`
       # declares that the project has none. `rigor sig-gen --params=observed` harvests call-site observations
@@ -77,10 +81,9 @@ module Rigor
         "inline_declared" => "write"
       },
       # ADR-17 — project-side monkey-patch pre-evaluation. Empty by default; users opt in by listing explicit
-      # files that the analyzer walks before per-file inference so patched-method declarations are visible
-      # across the project (e.g. `lib/core_ext/string_extensions.rb`). Slice 1 plumbing only — listed files
-      # are validated at config-load time (`pre-eval.file-not-found` on a missing path), but the dispatcher
-      # tier consuming the registry lands in slice 2.
+      # files (or globs) that the analyzer walks before per-file inference so patched-method declarations are
+      # visible across the project (e.g. `lib/core_ext/string_extensions.rb`). A missing literal path surfaces
+      # as `pre-eval.file-not-found`.
       "pre_eval" => [],
       # ADR-22 — baseline file path. nil (default) means no baseline is loaded; the `false` literal is
       # treated as the explicit-disable form for `.rigor.yml`-side override of an upstream `.rigor.dist.yml`
@@ -229,6 +232,11 @@ module Rigor
     PATH_KEYS = %w[paths signature_paths test_paths pre_eval].freeze
     private_constant :PATH_KEYS
 
+    # The single-path sibling of {PATH_KEYS}: resolved the same way, but kept a String rather than wrapped in an
+    # Array.
+    SCALAR_PATH_KEYS = %w[core_root].freeze
+    private_constant :SCALAR_PATH_KEYS
+
     # Top-level keys this implementation DECLARES but never reads — see `docs/internal-spec/config.md`
     # § "Reserved namespaces" and ADR-99.
     #
@@ -271,7 +279,8 @@ module Rigor
 
     attr_reader :target_ruby, :paths, :exclude_patterns, :plugins, :cache_path, :cache_max_bytes,
                 :cache_validation, :disabled_rules,
-                :libraries, :signature_paths, :test_paths, :fold_platform_specific_paths, :parameter_inference,
+                :libraries, :signature_paths, :core_root, :test_paths, :fold_platform_specific_paths,
+                :parameter_inference,
                 :plugins_isolation,
                 :plugins_io_network, :plugins_io_allowed_paths,
                 :plugins_io_allowed_url_hosts,
@@ -490,6 +499,7 @@ module Rigor
 
       out = data.dup
       PATH_KEYS.each { |key| resolve_path_key!(out, key, base_dir) }
+      SCALAR_PATH_KEYS.each { |key| resolve_scalar_path_key!(out, key, base_dir) }
       resolve_plugins_io_paths!(out, base_dir)
       out
     end
@@ -500,6 +510,12 @@ module Rigor
       out[key] = Array(out[key]).map { |p| ConfigPath.absolute(p.to_s, base_dir) }
     end
 
+    def self.resolve_scalar_path_key!(out, key, base_dir)
+      return unless out.key?(key) && out[key].is_a?(String)
+
+      out[key] = ConfigPath.absolute(out[key], base_dir)
+    end
+
     def self.resolve_plugins_io_paths!(out, base_dir)
       plugins_io = out["plugins_io"]
       return unless plugins_io.is_a?(Hash) && plugins_io["allowed_paths"]
@@ -582,6 +598,7 @@ module Rigor
       @libraries = Array(data.fetch("libraries", DEFAULTS.fetch("libraries"))).map(&:to_s).freeze
       sig_paths = data.fetch("signature_paths", DEFAULTS.fetch("signature_paths"))
       @signature_paths = sig_paths.nil? ? nil : Array(sig_paths).map(&:to_s).freeze
+      @core_root = coerce_core_root(data.fetch("core_root", DEFAULTS.fetch("core_root")))
       test_paths = data.fetch("test_paths", DEFAULTS.fetch("test_paths"))
       @test_paths = test_paths.nil? ? nil : Array(test_paths).map(&:to_s).freeze
       @sig_gen_inline_declared = coerce_sig_gen_inline_declared(data.fetch("sig_gen", nil))
@@ -595,18 +612,13 @@ module Rigor
       # ADR-67 WD6a — resolve to a strict Boolean so a truthy non-`true` value (e.g. a stray String) does not
       # silently enable the gate; only the literal `true` activates the check-walk collector pre-pass.
       @parameter_inference = data.fetch("parameter_inference", DEFAULTS.fetch("parameter_inference")) == true
-      # Resolved before `@effects` — ADR-103 WD15's "effects-on-by-default" reads {#bleeding_edge_active?},
-      # which reads `@bleeding_edge_active_ids`.
-      @bleeding_edge = coerce_bleeding_edge(
-        data.fetch("bleeding_edge", DEFAULTS.fetch("bleeding_edge"))
-      )
-      @bleeding_edge_severity_overrides = BleedingEdge.severity_overrides_for(@bleeding_edge)
-      @bleeding_edge_active_ids = BleedingEdge.active_ids_for(@bleeding_edge)
       # ADR-103 WD13 — presence, not truthiness: `effects:` written with no body parses as nil and still
-      # means "on", so the key's presence in the loaded data is what {#effects_enabled?} reads.
-      @effects = coerce_effects(data, effects_key_present: effects_key_present)
-      coerce_effects_snapshot(@effects)
-      coerce_effects_policy(@effects)
+      # means "on", so the key's presence in the loaded data is what {#effects_enabled?} reads. The raw
+      # input is kept so {#with_bleeding_edge} re-derives the effects block from the same source.
+      @effects_key_present = effects_key_present
+      @effects_written = Ractor.make_shareable(data.fetch("effects", false))
+      derive_bleeding_edge(data.fetch("bleeding_edge", DEFAULTS.fetch("bleeding_edge")))
+      derive_effects
       @cache_path = cache.fetch("path").to_s
       raw_max = cache.fetch("max_bytes")
       @cache_max_bytes = raw_max.nil? ? nil : Integer(raw_max)
@@ -672,6 +684,7 @@ module Rigor
         "disable" => disabled_rules,
         "libraries" => libraries,
         "signature_paths" => signature_paths,
+        "core_root" => core_root,
         # `test_paths:` is deliberately absent, as `effects:` is: `to_h` feeds the run cache key and the
         # incremental-snapshot fingerprint, and the test roots change no diagnostic, so editing them must not
         # invalidate either. `sig_gen:` is absent for the same reason: only `rigor sig-gen` reads it.
@@ -752,15 +765,14 @@ module Rigor
     # It is a frozen `dup` with the bleeding-edge ivars re-set: `dup` returns an unfrozen shallow copy
     # (every other ivar is the receiver's deeply-frozen value, safe to share read-only), the replacements
     # are themselves deeply frozen, and the re-`freeze` keeps the result `Ractor.shareable?` for the worker
-    # path. **Every ivar `#initialize` derives from `@bleeding_edge` has to be re-derived here** — the
-    # selector, the severity map, and the active-id set the {#bleeding_edge_active?} predicate reads.
+    # path. **Every ivar `#initialize` derives from the bleeding-edge selector has to be re-derived here** — it
+    # calls the same {#derive_bleeding_edge} and {#derive_effects} that `#initialize` does, so the selector,
+    # the severity map, the active-id set and the `effects:` default (ADR-103 WD15's "effects-on-by-default")
+    # all follow the new value, and a derived ivar added to `#initialize` is picked up without a second edit.
     def with_bleeding_edge(value)
-      selector = coerce_bleeding_edge(value)
       copy = dup
-      copy.instance_variable_set(:@bleeding_edge, selector)
-      copy.instance_variable_set(:@bleeding_edge_severity_overrides,
-                                 BleedingEdge.severity_overrides_for(selector))
-      copy.instance_variable_set(:@bleeding_edge_active_ids, BleedingEdge.active_ids_for(selector))
+      copy.send(:derive_bleeding_edge, value)
+      copy.send(:derive_effects)
       copy.freeze
     end
 
@@ -794,19 +806,38 @@ module Rigor
     #
     # Same `dup` + re-`freeze` shape as {#with_bleeding_edge}: every other ivar is the receiver's deeply
     # frozen value, safe to share read-only, and the result stays `Ractor.shareable?` for the worker path.
+    # The implicit block is recorded as a written empty one, so a later {#with_bleeding_edge} re-derives
+    # it instead of falling back to the absent-key default and dropping it.
     def with_effects_enabled
       return self if effects_enabled?
 
       copy = dup
-      copy.instance_variable_set(:@effects, {}.freeze)
-      # The implicit block defaults like a written one. `rigor effects` emits no diagnostic either way,
-      # but the two configurations must not differ in a field a later reader could branch on.
-      copy.instance_variable_set(:@effects_check, true)
+      copy.instance_variable_set(:@effects_key_present, true)
+      copy.instance_variable_set(:@effects_written, {}.freeze)
+      copy.send(:derive_effects)
       copy.freeze
     end
 
     private
 
+    # ADR-50 § WD2 / ADR-103 WD15 — derives the bleeding-edge selector and the two ivars the
+    # {#bleeding_edge_active?} predicate and the severity resolution read. `#initialize` and
+    # {#with_bleeding_edge} both call this, so there is one derivation to keep in step.
+    def derive_bleeding_edge(value)
+      @bleeding_edge = coerce_bleeding_edge(value)
+      @bleeding_edge_severity_overrides = BleedingEdge.severity_overrides_for(@bleeding_edge)
+      @bleeding_edge_active_ids = BleedingEdge.active_ids_for(@bleeding_edge)
+    end
+
+    # ADR-103 WD13 / WD15 — derives the `effects:` block and its snapshot and policy ivars from the raw
+    # `effects:` input the instance kept (`@effects_written`, `@effects_key_present`). The effects-on-by-default
+    # default reads the active-id set, so {#derive_bleeding_edge} must run first.
+    def derive_effects
+      @effects = coerce_effects(@effects_written, effects_key_present: @effects_key_present)
+      coerce_effects_snapshot(@effects)
+      coerce_effects_policy(@effects)
+    end
+
     # ADR-103 WD13 — the `effects:` block, or nil when the key is absent or explicitly `false`. A
     # present-but-empty key (`effects:` alone, which YAML parses as nil) and `effects: {}` are the same
     # thing: collection on, every sub-key defaulted. A non-Hash body is normalised to `{}` rather than
@@ -818,8 +849,7 @@ module Rigor
     # as `effects: {}` when the "effects-on-by-default" bleeding-edge feature is adopted. An explicit
     # `effects: false` — `effects_key_present == true` — always stays off regardless of the feature, and a
     # written block always wins outright: the feature can only fill an *absence*.
-    def coerce_effects(data, effects_key_present:)
-      value = data.fetch("effects", false)
+    def coerce_effects(value, effects_key_present:)
       return {}.freeze if value == false && !effects_key_present && effects_forced_on_by_bleeding_edge?
       return nil if value == false
 
@@ -1054,7 +1084,7 @@ module Rigor
       end
     end
 
-    # `target_ruby` is passed to `Prism.parse_file(path, version:)` at the analyser's three parse sites
+    # `target_ruby` is passed as Prism's `version:` option at the analyser's parse sites
     # (`Analysis::Runner`, `CLI::TypeOfCommand`, `CLI::TypeScanCommand`) so projects that target an older
     # Ruby get parse errors for syntax their target doesn't support. Format validation here is loose —
     # accepts any `<major>.<minor>` or `<major>.<minor>.<patch>` form, plus the literal `"latest"`. Prism
@@ -1097,6 +1127,18 @@ module Rigor
     # ADR-22 WD2 (b) — `baseline: <path>` activates the file; `baseline: false` is the explicit-disable form
     # (useful in `.rigor.yml` to override an upstream `.rigor.dist.yml` that names a baseline). `nil`
     # (default / absent key) is also "no baseline".
+    # Issue #2517 — the directory's existence and contents are checked where the environment is built
+    # ({Environment::CoreRoot.validate!}), not here: `rigor init`, `rigor doctor` and the language server's reload
+    # load a configuration without building an environment, and must still be able to read one naming a core that
+    # is not generated yet.
+    def coerce_core_root(value)
+      return nil if value.nil?
+      raise ConfigurationError, "core_root must be a directory path, got #{value.inspect}" unless value.is_a?(String)
+      raise ConfigurationError, "core_root must not be empty" if value.strip.empty?
+
+      value.dup.freeze
+    end
+
     def coerce_baseline_path(value)
       return nil if value.nil? || value == false
 

data/lib/rigor/effects/definition_context.rb

@@ -58,11 +58,9 @@ module Rigor
         node.is_a?(Prism::SingletonClassNode) || (node.is_a?(Prism::CallNode) && node.block.is_a?(Prism::BlockNode))
       end
 
-      # A class body.
       CLASS_BODY = of(:class, false)
       # A `class << self` body: `self` and the definee are both the singleton class.
       SINGLETON_CLASS_BODY = of(:singleton_class, true)
-      # The body of an instance method of the class.
       INSTANCE_METHOD_BODY = of(:instance, false)
       # The top level, where `self` is `main`, an instance of `Object`, and a `def` defines `Object#m`.
       TOP_LEVEL = INSTANCE_METHOD_BODY

data/lib/rigor/effects/envelope.rb

@@ -8,7 +8,7 @@ module Rigor
     # An author-declared upper bound on one method's effect labels (ADR-103 WD1; normative in
     # `docs/type-specification/effect-labels.md` § Effect envelopes).
     #
-    # Four facts and one seam:
+    # Its facts:
     #
     # - {#owner_key} — the method key the envelope binds (`Class#m` / `Class.m`). A class-level
     #   envelope is read once and {#rebind}ed onto each method of that class discovery knows.

data/lib/rigor/effects/framework_units.rb

@@ -69,7 +69,7 @@ module Rigor
       VALIDATION_TRIGGERS = %w[valid? invalid? validate!].freeze
       SINGLETON_SAVE_TRIGGERS = %w[create create!].freeze
 
-      # `initialize` is not a mailer action, and neither is a method a plugin would want double-counted.
+      # `initialize` is not a mailer action.
       NON_ACTION_METHODS = %w[initialize].to_set.freeze
 
       module_function