rigortype 0.2.9 → 0.3.1

data/lib/rigor/config_audit.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
+require "did_you_mean"
+
 require_relative "signature_path_audit"
-require_relative "analysis/check_rules"
+# ADR-87 WD4 — only the pure rule-id table (`ALL_RULES` / `RULE_FAMILIES`) is needed, so require the light
+# `rule_ids.rb` rather than the engine-pulling `check_rules.rb`; keeps `config_audit` (loaded by every check)
+# off the inference engine so the boot-slimming hit path stays engine-free.
+require_relative "analysis/check_rules/rule_ids"
 
 module Rigor
   # Audits a loaded {Configuration} for the class of mistake where a configured value
@@ -36,12 +41,53 @@ module Rigor
     #   paths resolve against (the CLI's CWD), used only by the explicit-path checks.
     # @return [Array<Warning>]
     def self.warnings(configuration, project_root: Dir.pwd)
-      signature_path_warnings(configuration) +
+      unknown_key_warnings(configuration) +
+        signature_path_warnings(configuration) +
         library_warnings(configuration) +
         rule_token_warnings(configuration) +
         explicit_path_warnings(configuration, project_root)
     end
 
+    # Top-level keys the loader does not own. The archetypal case is a typo — `excludee:` for
+    # `exclude:` — which the loader drops in silence, so the exclusion never applies and the run
+    # reports errors from the very files the user meant to skip, with nothing anywhere saying the key
+    # did nothing. That is exactly this module's class of mistake, and it was the one whole-key
+    # instance of it going unwarned.
+    #
+    # A reserved namespace ({Configuration::RESERVED_NAMESPACES}) is unknown *on purpose* — another
+    # implementation reads it from the same file — so it is exempt. {Configuration#unknown_keys}
+    # already applies that exemption; warning here would push users to delete the key their other
+    # tool needs.
+    #
+    # **Top level only, and deliberately.** A nested check would have to name each group's known keys,
+    # and DEFAULTS cannot supply them: `DEFAULTS["dependencies"]` carries `source_inference` and
+    # `budget_per_gem` but not `budget_overrun_strategy`, which is real (`Configuration::Dependencies`
+    # reads it), documented, and schema-declared — so a DEFAULTS-keyed nested check would flag a
+    # working config. `severity_overrides:` is an open map of rule ids besides. Nested unknown keys are
+    # the schema tier's job: every nested object in `schemas/rigor-config.schema.json` is
+    # `additionalProperties: false`, and `config_schema_spec` keeps it complete
+    # ([ADR-99](../../docs/adr/99-config-schema-authority.md), `docs/internal-spec/config.md`).
+    def self.unknown_key_warnings(configuration)
+      configuration.unknown_keys.map do |key|
+        suggestion = suggest_config_key(key)
+        hint = suggestion ? " Did you mean `#{suggestion}`?" : ""
+        Warning.new(
+          kind: :unknown_key,
+          message: "`#{key}` is not a recognized configuration key; it has no effect.#{hint}",
+          fields: { "key" => key, "suggestion" => suggestion }
+        )
+      end
+    end
+
+    # Nearest known key, or nil. Uses `DidYouMean::SpellChecker` — the engine behind Ruby's own
+    # `NoMethodError` hints, and the one `Plugin::Base.suggest` wraps. Called directly rather than
+    # through that helper because `plugin/base.rb` pulls Prism and the diagnostic model in, and
+    # ADR-87 WD4 keeps this file (loaded by every check) off that path; `did_you_mean` is stdlib.
+    def self.suggest_config_key(key)
+      DidYouMean::SpellChecker.new(dictionary: Configuration::KNOWN_KEYS).correct(key.to_s).first
+    end
+    private_class_method :suggest_config_key
+
     # `signature_paths:` entries that resolve to nothing — delegated to {SignaturePathAudit},
     # which mirrors the loader's `directory?` + recursive `**/*.rbs` acceptance test.
     def self.signature_path_warnings(configuration)

data/lib/rigor/configuration/severity_profile.rb

@@ -37,11 +37,15 @@ module Rigor
           "call.wrong-arity" => :error,
           "call.argument-type-mismatch" => :warning,
           "call.possible-nil-receiver" => :warning,
+          "call.raise-non-exception" => :warning,
           "flow.always-raises" => :warning,
           "flow.unreachable-branch" => :info,
           "flow.dead-assignment" => :info,
           "flow.always-truthy-condition" => :info,
           "flow.unreachable-clause" => :info,
+          "flow.duplicate-hash-key" => :info,
+          "flow.return-in-ensure" => :info,
+          "flow.shadowed-rescue-clause" => :info,
           "assert.type-mismatch" => :error,
           "dump.type" => :info,
           "def.return-type-mismatch" => :warning,
@@ -50,6 +54,16 @@ module Rigor
           "def.override-return-widened" => :off,
           "def.override-param-narrowed" => :off,
           "def.ivar-write-mismatch" => :warning,
+          # ADR-8 companion (PHPStan IgnoreParseErrorRule-modelled): a broken suppression comment is
+          # equally bad in every profile — it silently fails to do what the author believes it does — so
+          # both rules stay :warning across all three profiles (including strict).
+          "suppression.unknown-rule" => :warning,
+          "suppression.empty" => :warning,
+          "suppression.unknown-marker" => :warning,
+          # ADR-100 — a new required diagnostic (ADR-50 WD1), so it is `:off` in every shipped profile and
+          # reaches a user only through the `use-of-void-value` bleeding-edge feature, which overrides this
+          # to `:warning`.
+          "static.value-use.void" => :off,
           # Opt-in author assertion: you only see it if you wrote a
           # `conforms-to` directive, so it stays a :warning even in
           # lenient — it is never unsolicited noise.
@@ -62,6 +76,7 @@ module Rigor
           "call.wrong-arity" => :error,
           "call.argument-type-mismatch" => :error,
           "call.possible-nil-receiver" => :error,
+          "call.raise-non-exception" => :error,
           "flow.always-raises" => :error,
           "flow.unreachable-branch" => :warning,
           "flow.dead-assignment" => :warning,
@@ -71,6 +86,9 @@ module Rigor
           # green; promote to :warning once Mastodon/GitLab/Redmine triage
           # to zero net false positives.
           "flow.unreachable-clause" => :info,
+          "flow.duplicate-hash-key" => :warning,
+          "flow.return-in-ensure" => :warning,
+          "flow.shadowed-rescue-clause" => :warning,
           "assert.type-mismatch" => :error,
           "dump.type" => :info,
           "def.return-type-mismatch" => :warning,
@@ -79,6 +97,10 @@ module Rigor
           "def.override-return-widened" => :warning,
           "def.override-param-narrowed" => :warning,
           "def.ivar-write-mismatch" => :warning,
+          "suppression.unknown-rule" => :warning,
+          "suppression.empty" => :warning,
+          "suppression.unknown-marker" => :warning,
+          "static.value-use.void" => :off,
           "rbs_extended.unsatisfied-conformance" => :warning
         }.freeze,
         strict: {
@@ -88,6 +110,7 @@ module Rigor
           "call.wrong-arity" => :error,
           "call.argument-type-mismatch" => :error,
           "call.possible-nil-receiver" => :error,
+          "call.raise-non-exception" => :error,
           "flow.always-raises" => :error,
           "flow.unreachable-branch" => :error,
           "flow.dead-assignment" => :error,
@@ -96,6 +119,9 @@ module Rigor
           # below its :error siblings) while it proves out — see the
           # balanced-profile note above.
           "flow.unreachable-clause" => :warning,
+          "flow.duplicate-hash-key" => :error,
+          "flow.return-in-ensure" => :error,
+          "flow.shadowed-rescue-clause" => :error,
           "assert.type-mismatch" => :error,
           "dump.type" => :error,
           "def.return-type-mismatch" => :error,
@@ -104,6 +130,11 @@ module Rigor
           "def.override-return-widened" => :error,
           "def.override-param-narrowed" => :error,
           "def.ivar-write-mismatch" => :error,
+          "suppression.unknown-rule" => :warning,
+          "suppression.empty" => :warning,
+          "suppression.unknown-marker" => :warning,
+          # `:off` even under strict: the gate is `bleeding_edge:`, not the profile (ADR-50 WD1 / ADR-100).
+          "static.value-use.void" => :off,
           "rbs_extended.unsatisfied-conformance" => :error
         }.freeze
       }.freeze

data/lib/rigor/configuration.rb

@@ -3,6 +3,7 @@
 require "yaml"
 
 require_relative "bleeding_edge"
+require_relative "ci_detector"
 require_relative "configuration/dependencies"
 require_relative "configuration/severity_profile"
 
@@ -55,6 +56,13 @@ module Rigor
       # filtering — the path must be named here (WD2 (b) of ADR-22).
       "baseline" => nil,
       "fold_platform_specific_paths" => false,
+      # ADR-67 WD6a — opt-in call-site parameter type inference on the `check` walk. When `true`, `rigor
+      # check` runs the {Inference::ParameterInferenceCollector} as a one-round pre-pass into the discovery
+      # seed, so an undeclared `def` / `initialize` / setter parameter is typed to the union of its resolved
+      # call-site argument types (precision-additive only — the in-body negative rules decline on the inferred
+      # lower bound, WD6b). `false` (the default, resolved off by every severity profile) keeps the table empty
+      # and the run byte-identical to today. Mutually exclusive with `--incremental` (WD6c).
+      "parameter_inference" => false,
       "cache" => {
         "path" => ".rigor/cache",
         # LRU eviction cap in bytes (ADR-54 WD3). The least-recently-used entries are removed at the end of a
@@ -63,7 +71,18 @@ module Rigor
         # would otherwise ever delete; a full active per-project set is ~2 MB, so the cap never touches live
         # entries. Set explicitly to `null` to disable eviction (pre-WD3 behaviour: the cache grows until
         # `--clear-cache`).
-        "max_bytes" => 268_435_456
+        "max_bytes" => 268_435_456,
+        # ADR-87 WD1 — file-freshness validation strategy. `"stat"` validates a recorded file
+        # dependency by stat-ing it first and re-hashing only when the `(size, mtime_ns, ctime_ns, inode)`
+        # tuple moved (or the racy window fires), so an unchanged monorepo hashes ~0 bytes on a warm run.
+        # `"digest"` restores the pre-ADR-87 behaviour of SHA-256'ing every recorded file on every run — the
+        # per-run escape hatch is the `RIGOR_STRICT_VALIDATION=1` env var, which wins over this setting.
+        # `"auto"` (default, #190) resolves per environment: `"digest"` when {CiDetector} recognises a CI
+        # provider — a fresh checkout regenerates every stat tuple, so the stat tier can never short-circuit
+        # there and stat-signature glob slots would recompute on every run — and `"stat"` everywhere else.
+        # A self-hosted runner with a persistent workspace opts back into the stat floor with an explicit
+        # `"stat"` (or `RIGOR_CI_DETECT=0`).
+        "validation" => "auto"
       },
       "plugins_io" => {
         "network" => "disabled",
@@ -143,9 +162,45 @@ module Rigor
     PATH_KEYS = %w[paths signature_paths pre_eval].freeze
     private_constant :PATH_KEYS
 
+    # Top-level keys this implementation DECLARES but never reads — see `docs/internal-spec/config.md`
+    # § "Reserved namespaces" and ADR-99.
+    #
+    # A sibling implementation (`rigor-rs`, which vendors our schema rather than keeping its own)
+    # groups keys for concepts we do not have under its own namespace, so one `.rigor.yml` feeds both.
+    # Such a key answers to the SCHEMA TIER ONLY: it is type-checked where it is written, and here it
+    # is never read, never validated, never coerced, and never an error however invalid its value.
+    #
+    # That is already the emergent behaviour — `#initialize` fetches each key it owns and never
+    # enumerates the rest — so this constant does not gate the runtime. It exists to make the
+    # reservation FINDABLE by the next person adding config validation (#166 is exactly that), and to
+    # give the schema-parity spec something to key on: a reserved namespace is by definition absent
+    # from DEFAULTS, so the DEFAULTS-driven schema gate can never see it.
+    RESERVED_NAMESPACES = %w[rigor_rs].freeze
+
+    # Every top-level key a conforming `.rigor.yml` may carry: the keys this implementation owns, plus
+    # `includes:`, plus the namespaces reserved for another implementation. Anything else is recorded in
+    # {#unknown_keys} and warned about by {ConfigAudit}, and is also the did-you-mean dictionary for a
+    # near-miss.
+    #
+    # `includes:` is a load-time directive — {load_with_includes} `delete`s it while merging, so it never
+    # reaches `#initialize` and could not be seen as unknown regardless. It is listed because a user
+    # legitimately writes it, so a typo like `include:` must be able to suggest it.
+    KNOWN_KEYS = (DEFAULTS.keys + %w[includes] + RESERVED_NAMESPACES).freeze
+
+    # Top-level keys the loaded config carried that this implementation does not own — neither a
+    # {DEFAULTS} key, nor `includes:`, nor a reserved namespace. Recorded rather than acted on: an
+    # unknown key stays as inert at run time as it has always been, and {ConfigAudit} turns the record
+    # into a warning. Empty for every conforming config.
+    #
+    # This exists because `#initialize` fetches each key it owns and never enumerates the rest, so by
+    # the time anything holds a Configuration the unknown keys are gone. The audit reads a
+    # Configuration, so without this the class of mistake it exists to catch — a value that silently
+    # resolves to nothing — was structurally invisible to it for whole keys.
+    attr_reader :unknown_keys
+
     attr_reader :target_ruby, :paths, :exclude_patterns, :plugins, :cache_path, :cache_max_bytes,
-                :disabled_rules,
-                :libraries, :signature_paths, :fold_platform_specific_paths,
+                :cache_validation, :disabled_rules,
+                :libraries, :signature_paths, :fold_platform_specific_paths, :parameter_inference,
                 :plugins_io_network, :plugins_io_allowed_paths,
                 :plugins_io_allowed_url_hosts,
                 :severity_profile, :severity_overrides,
@@ -168,10 +223,67 @@ module Rigor
     # [PHPStan](https://phpstan.org/config-reference#paths).
     def self.load(path = nil)
       resolved = path || discover
-      return new(DEFAULTS) if resolved.nil? || !File.exist?(resolved)
+      data =
+        if resolved.nil? || !File.exist?(resolved)
+          DEFAULTS
+        else
+          DEFAULTS.merge(load_with_includes(resolved))
+        end
+      new(autowire_default_plugins(data))
+    end
 
-      data = load_with_includes(resolved)
-      new(DEFAULTS.merge(data))
+    # ADR-93 WD2 — the one bundled plugin default-wired without a `plugins:` entry. `rigor-rbs-inline` is the
+    # gem; `rbs-inline` is its manifest id (the loader raises on a duplicate id, so both forms count as
+    # "already listed").
+    AUTOWIRED_RBS_INLINE_GEM = "rigor-rbs-inline"
+    AUTOWIRED_RBS_INLINE_ID = "rbs-inline"
+
+    # ADR-93 WD2 — default-wire the bundled `rigor-rbs-inline` plugin, in WD1's annotation-gated,
+    # magic-comment-free mode, when the upstream `rbs-inline` library is resolvable and the user has not
+    # already listed the plugin. Runs from {load} only — the real-project route — never from a bare
+    # {Configuration.new}, so the suite's unit constructions do not auto-wire. The gate is presence-based
+    # (ADR-72's shape): an annotation-free project pays only a comment scan and contributes nothing, so
+    # wiring it on cannot regress the run. This partially reverses the ADR-27/ADR-31 auto-load deferral for
+    # this one bundled plugin (the executed code is already vendored, not arbitrary third-party plugin code).
+    # Opt out with a `plugins:` entry disabling it (`enabled: false`), or per-file `# rbs_inline: disabled`.
+    def self.autowire_default_plugins(data)
+      entries = Array(data["plugins"])
+      return data if entries.any? { |entry| rbs_inline_plugin_entry?(entry) }
+      return data unless rbs_inline_library_resolvable?
+
+      merged = data.dup
+      merged["plugins"] = entries + [{
+        "gem" => AUTOWIRED_RBS_INLINE_GEM,
+        "id" => AUTOWIRED_RBS_INLINE_ID,
+        "config" => { "require_magic_comment" => false }
+      }]
+      merged
+    end
+
+    # True when a `plugins:` entry (String or Hash, string- or symbol-keyed) already references the
+    # `rigor-rbs-inline` plugin by gem name or by manifest id. Single-homed here so the CLI's
+    # `--treat-all-as-inline-rbs` injection and the WD2 auto-wire gate agree on what "already listed" means.
+    def self.rbs_inline_plugin_entry?(entry)
+      case entry
+      when String
+        entry == AUTOWIRED_RBS_INLINE_GEM
+      when Hash
+        string_keyed = entry.to_h { |k, v| [k.to_s, v] }
+        string_keyed["gem"] == AUTOWIRED_RBS_INLINE_GEM || string_keyed["id"] == AUTOWIRED_RBS_INLINE_ID
+      else
+        false
+      end
+    end
+
+    # A probe with no load side effect: it does not `require` the library, only asks whether RubyGems can
+    # resolve the name. `Gem::Specification.find_by_name` raises `Gem::MissingSpecError` (a `Gem::LoadError`)
+    # when the gem is absent — the standalone `gem install rigortype` case, WD3's residual. ADR-90's
+    # project-bundle fallback resolves the same name at the plugin's own `require` time.
+    def self.rbs_inline_library_resolvable?
+      Gem::Specification.find_by_name("rbs-inline")
+      true
+    rescue Gem::LoadError
+      false
     end
 
     # Returns the path to the config file Rigor would load under auto-discovery, or `nil` when neither
@@ -280,6 +392,10 @@ module Rigor
 
     # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
     def initialize(data = DEFAULTS)
+      # Record before the per-key fetches below discard the evidence. Top level only, deliberately —
+      # see {ConfigAudit.unknown_key_warnings} for why a nested check cannot key on DEFAULTS.
+      @unknown_keys = (data.keys.map(&:to_s) - KNOWN_KEYS).sort.freeze
+
       cache = DEFAULTS.fetch("cache").merge(data.fetch("cache", {}))
       plugins_io = DEFAULTS.fetch("plugins_io").merge(data.fetch("plugins_io", {}))
 
@@ -300,10 +416,14 @@ module Rigor
       @baseline_path = coerce_baseline_path(data.fetch("baseline", DEFAULTS.fetch("baseline")))
       @fold_platform_specific_paths = data.fetch(
         "fold_platform_specific_paths", DEFAULTS.fetch("fold_platform_specific_paths")
-      ) == true
+      )
+      # 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
       @cache_path = cache.fetch("path").to_s
       raw_max = cache.fetch("max_bytes")
       @cache_max_bytes = raw_max.nil? ? nil : Integer(raw_max)
+      @cache_validation = coerce_cache_validation(cache.fetch("validation", "auto"))
       @plugins_io_network = coerce_network_policy(plugins_io.fetch("network"))
       @plugins_io_allowed_paths = Array(plugins_io.fetch("allowed_paths")).map(&:to_s).freeze
       @plugins_io_allowed_url_hosts = Array(plugins_io.fetch("allowed_url_hosts")).map(&:to_s).freeze
@@ -340,6 +460,20 @@ module Rigor
     end
     # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
+    # Resolves the `cache.validation` tri-state to the boolean the run installs via
+    # {Cache::FileDigest.with_run}'s `strict:`. Explicit `"digest"` / `"stat"` win outright; the `"auto"`
+    # default is strict exactly when {CiDetector} recognises a CI provider (#190) — deliberately NOT stored at
+    # construction so the resolution honours the environment of the run, not of `Configuration.load`, and the
+    # frozen carrier stays env-independent. `RIGOR_STRICT_VALIDATION=1` is enforced separately inside
+    # {Cache::FileDigest.strict_validation?} and wins over all three values.
+    def cache_validation_strict?(env = ENV)
+      case cache_validation
+      when "digest" then true
+      when "stat" then false
+      else !CiDetector.detect(env).nil?
+      end
+    end
+
     def to_h # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
       {
         "target_ruby" => target_ruby,
@@ -351,9 +485,11 @@ module Rigor
         "signature_paths" => signature_paths,
         "pre_eval" => pre_eval,
         "fold_platform_specific_paths" => fold_platform_specific_paths,
+        "parameter_inference" => parameter_inference,
         "cache" => {
           "path" => cache_path,
-          "max_bytes" => cache_max_bytes
+          "max_bytes" => cache_max_bytes,
+          "validation" => cache_validation
         },
         "plugins_io" => {
           "network" => plugins_io_network.to_s,
@@ -483,6 +619,18 @@ module Rigor
       value.to_s
     end
 
+    # ADR-87 WD1 — `cache.validation` is `"auto"` (default), `"stat"`, or `"digest"`. An unrecognised value
+    # fails soft to the default rather than aborting a check over a typo — the strict `"digest"` behaviour is
+    # the safe fallback either way, and the always-available `RIGOR_STRICT_VALIDATION=1` env escape hatch does
+    # not depend on this value being valid.
+    VALID_CACHE_VALIDATIONS = %w[auto stat digest].freeze
+    private_constant :VALID_CACHE_VALIDATIONS
+
+    def coerce_cache_validation(value)
+      str = value.to_s
+      VALID_CACHE_VALIDATIONS.include?(str) ? str : "auto"
+    end
+
     def coerce_network_policy(value)
       sym = value.to_sym
       unless VALID_NETWORK_POLICIES.include?(sym)

data/lib/rigor/environment/default_libraries.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Rigor
+  class Environment
+    # Slice A stdlib expansion. Stdlib libraries that `Environment.for_project` loads on top of RBS core
+    # unless the caller passes an explicit `libraries:` array. Each entry MUST be a stdlib library name
+    # accepted by `RBS::EnvironmentLoader#has_library?`; unknown libraries MUST fail-soft
+    # (`RbsLoader#build_env` already filters through `has_library?`). The default set covers the common
+    # stdlib surface a Ruby program is likely to import, plus the analyzer-adjacent gems shipping their own
+    # RBS in this bundle (`prism`, `rbs`). The list below is the enumeration — no prose gloss restates a
+    # subset of it, here or in `docs/internal-spec/inference-engine.md` § Environment Surface, because a
+    # restated subset silently rots as entries are added. On hosts where one of these libraries is not
+    # installed, the loader silently drops it.
+    #
+    # Callers MAY add to the default by passing `libraries: %w[csv ...]`; the explicit list is appended to
+    # `DEFAULT_LIBRARIES` and de-duplicated. Callers that need a strictly RBS-core view MUST construct an
+    # `RbsLoader` directly instead of going through `for_project`.
+    #
+    # ADR-87 WD4 — extracted to its own light file (no engine requires) so the boot-slimming hit probe can
+    # reconstruct `Environment.for_project`'s merged library list — which feeds the run cache KEY's
+    # `rbs.libraries` slot — WITHOUT building the RBS environment (or loading the inference engine).
+    DEFAULT_LIBRARIES = %w[
+      pathname optparse json yaml fileutils tempfile tmpdir
+      stringio forwardable digest securerandom
+      uri logger date
+      pp delegate observable abbrev find tsort singleton
+      shellwords benchmark base64 did_you_mean
+      monitor mutex_m timeout
+      open3 erb etc ipaddr bigdecimal bigdecimal-math
+      prettyprint random-formatter time open-uri resolv
+      csv pstore objspace io-console cgi cgi-escape
+      strscan
+      prism rbs
+    ].freeze
+  end
+end

data/lib/rigor/environment/rbs_loader.rb

@@ -90,10 +90,48 @@ module Rigor
           add_project_signatures(env, signature_paths)
           add_virtual_rbs(env, virtual_rbs)
           synthesize_missing_namespaces(env)
-          resolved = env.resolve_type_names
+          env, resolved = resolve_quarantining_virtual_collisions(env, virtual_rbs)
           stub_missing_referenced_types(env, resolved, project_sig_files(signature_paths))
         end
 
+        # True when `content` parses as an RBS signature. {#virtual_rbs_collision_quarantined} uses this to
+        # tell a collision-dropped virtual entry (parses, but absent from the env) from a parse-failed one
+        # (the synthesizer's own WD6 skip, reported separately).
+        def parseable_rbs?(content)
+          ::RBS::Parser.parse_signature(::RBS::Buffer.new(name: "(rigor: virtual parse check)", content: content))
+          true
+        rescue ::RBS::BaseError
+          false
+        end
+
+        # Backstop for a virtual-vs-anything `RBS::DuplicatedDeclarationError` that only materialises at
+        # `resolve_type_names` (which rebuilds the env from `sources`). {.add_virtual_rbs}'s transactional
+        # rescue already handles the add-time case — empirically everything on rbs 4.x — but the rbs gemspec
+        # range spans `>= 3.0, < 5.0` (ADR-79) and WHERE duplicate detection fires is an rbs-internal choice
+        # this code must not depend on. Resolution rule is the same as the add-time path: the explicit
+        # signature wins, the colliding VIRTUAL buffer is dropped whole (`RBS::Environment#unload`) and
+        # resolution retries; every pass removes at least one virtual buffer, so the loop is bounded by the
+        # virtual-entry count. A duplicate involving no virtual buffer (sig-vs-sig), or an env without
+        # `#unload` (rbs 3.x), re-raises into the existing one-warning degrade path.
+        #
+        # The dropped set is not returned: consumers recover it from the built env via
+        # {#virtual_rbs_collision_quarantined}, which also works on a cache HIT where this build never ran.
+        def resolve_quarantining_virtual_collisions(env, virtual_rbs)
+          virtual_names = virtual_rbs.to_set { |name, _content| name.to_s }
+          (virtual_names.size + 1).times do
+            return [env, env.resolve_type_names]
+          rescue ::RBS::DuplicatedDeclarationError => e
+            raise unless env.respond_to?(:unload)
+
+            culprits = e.decls.filter_map { |decl| decl.location&.buffer&.name }
+                              .uniq.select { |name| virtual_names.include?(name) }
+            raise if culprits.empty?
+
+            env = env.unload(culprits)
+          end
+          [env, env.resolve_type_names]
+        end
+
         # ADR-5 robustness, second tier. A project `signature_paths:` RBS that *references* a type no loaded
         # signature declares — `def x: () -> DRb::DRbServer` when the `drb` RBS is not available, or a stale
         # reference to its own removed `Textbringer::EditorError` — makes
@@ -356,9 +394,20 @@ module Rigor
             _, directives, decls = ::RBS::Parser.parse_signature(buffer)
             add_parsed_decls(env, buffer, directives, decls)
           rescue ::RBS::BaseError
-            # WD6 fail-soft: a single broken virtual RBS contribution does not pull the whole env down. The
-            # plugin layer records a `source-rbs-synthesis-failed` info diagnostic in slice 2; here we just
-            # skip the entry.
+            # WD6 fail-soft: a single broken virtual RBS contribution does not pull the whole env down — for
+            # a parse error, skipping the entry is enough. But `RBS::Environment#add_source` appends to
+            # `env.sources` BEFORE inserting decls, so when the raise is a mid-insert
+            # `RBS::DuplicatedDeclarationError` (the entry declares a constant the project's own `sig/`
+            # already declares — the expected state for a project migrating between `sig/` and inline
+            # annotations, not an authoring error), the POISONED SOURCE is left behind, and
+            # `resolve_type_names` — which rebuilds the env from `sources` — re-raises the same error outside
+            # this rescue and collapses the WHOLE env to nil (measured on herb: 1,490 classes → 0, `require`
+            # itself stopped resolving, 74 false `call.unresolved-toplevel`). Make the skip transactional:
+            # drop the poisoned source. The explicit `.rbs` declaration wins — the spec keeps standalone
+            # `.rbs` files "the preferred place for complete type definitions" (`overview.md`) — and
+            # {#warn_about_virtual_rbs_collisions} names the dropped file. `sources` is the rbs 4.x shape;
+            # under the 3.x API this degrades to today's behaviour.
+            env.sources.reject! { |source| source.buffer.name == buffer.name } if env.respond_to?(:sources)
           end
         end
 
@@ -478,6 +527,55 @@ module Rigor
         names_synthesized_in(SYNTHETIC_NAMESPACE_BUFFER)
       end
 
+      # The project `signature_paths:` files that were QUARANTINED this run (they do not parse, so
+      # {RbsLoader.add_project_signatures} skipped them to keep the rest of the env alive), as
+      # `[absolute_path, first_error_line]` pairs. Memoised per loader: the detection re-parses only the user's
+      # own `sig/` set, but every consumer (the `rbs.coverage.quarantined-signature` diagnostic, `rigor doctor`,
+      # the stderr banner) reads it, and a cache HIT reaches it too — the env was built with the file already
+      # quarantined, so the condition is invisible in the cached env itself.
+      #
+      # @return [Array<Array(String, String)>] empty when every `signature_paths:` file parses.
+      def quarantined_signatures
+        @state[:quarantined] ||= self.class.quarantined_project_signatures(@signature_paths).freeze
+      end
+
+      # The total RBS-environment build failure captured this run, or nil when the env built. Unlike
+      # {#quarantined_signatures} — which the env survives, one file lighter, and which is re-derived by
+      # re-parsing so a cache HIT reports it too — a total failure (typically `RBS::DuplicatedDeclarationError`:
+      # a `signature_paths:` entry redeclaring a constant/class Rigor's bundled RBS already ships) collapses the
+      # WHOLE env to nil. A failed build produces no cached success to hide behind (nothing is persisted, so
+      # every run re-attempts and re-raises), so this is captured directly in {#env}'s rescue rather than
+      # re-derived. Forcing `env` (any query does) populates it.
+      #
+      # @return [Array(String, String, Array<String>), nil] `[error_class_name, first_error_line,
+      #   conflicting_buffer_names]`, or nil when the environment built successfully.
+      def env_build_failure
+        env unless @state[:env_loaded]
+        @state[:env_build_failure]
+      end
+
+      # Virtual (inline-synthesized) contributions dropped by the collision quarantine
+      # ({.resolve_quarantining_virtual_collisions}): buffer names absent from the built env even though the
+      # entry's content is non-empty and parses (a parse failure is the synthesizer's own WD6 skip, reported
+      # through the synthesis reporter instead). Derived from the env rather than recorded during build —
+      # the {#quarantined_signatures} trick — so a cache HIT, which never runs the build, reports the same
+      # condition: the marshalled env simply lacks the dropped buffers.
+      #
+      # @return [Array<String>] virtual buffer names (source-file paths) whose contribution was dropped.
+      def virtual_rbs_collision_quarantined
+        @state[:virtual_rbs_collisions] ||= begin
+          built = @state[:env]
+          if built.nil? || @virtual_rbs.empty?
+            [].freeze
+          else
+            present = built.buffers.to_set(&:name)
+            @virtual_rbs.filter_map do |name, content|
+              name if !content.empty? && !present.include?(name) && self.class.parseable_rbs?(content)
+            end.freeze
+          end
+        end
+      end
+
       # The referenced-but-undeclared types {.stub_missing_referenced_types} stubbed so the project classes
       # that mention them could build (e.g. an unavailable `DRb::DRbServer`, or a stale
       # `Textbringer::EditorError`). Recovered off the built env like {#synthesized_namespaces}, so it
@@ -970,8 +1068,10 @@ module Rigor
         @state[:env_loaded] = true
         @state[:env] = cache_store ? cached_env : build_env
         warn_about_quarantined_signatures
+        warn_about_virtual_rbs_collisions
         @state[:env]
       rescue ::RBS::BaseError => e
+        record_env_build_failure(e)
         warn_about_env_build_failure_once(e)
         @state[:env] = nil
       end
@@ -982,10 +1082,15 @@ module Rigor
       # is the visibility half of the fix: a shrinking diagnostic count must never be mistaken for a clean run
       # when it actually means "your sig/ stopped loading". No-op when `signature_paths:` is empty (the cost is
       # then a single empty-set check) or every file parses.
+      #
+      # `rigor check` ALSO reports this as the `rbs.coverage.quarantined-signature` diagnostic, which is what
+      # reaches JSON / SARIF / CI annotations / the LSP. The banner is kept because the commands that build an
+      # env WITHOUT producing a diagnostic stream (`coverage`, `sig-gen`) have no other channel, and a silently
+      # degraded env is exactly what misleads there too.
       def warn_about_quarantined_signatures
         return if @state[:quarantine_warned]
 
-        quarantined = self.class.quarantined_project_signatures(@signature_paths)
+        quarantined = quarantined_signatures
         return if quarantined.empty?
 
         @state[:quarantine_warned] = true
@@ -1002,6 +1107,60 @@ module Rigor
         )
       end
 
+      # The collision twin of {#warn_about_quarantined_signatures}: name, once per run, the source files
+      # whose inline-synthesized RBS was dropped because it collides with a declaration another signature
+      # source already made ({.resolve_quarantining_virtual_collisions} — the explicit `.rbs` wins). Without
+      # this the drop is silent, and "my `#:` annotation does nothing" has no visible cause. Reads the
+      # derived {#virtual_rbs_collision_quarantined}, so a cache HIT warns identically.
+      def warn_about_virtual_rbs_collisions
+        return if @state[:virtual_collision_warned]
+
+        dropped = virtual_rbs_collision_quarantined
+        return if dropped.empty?
+
+        @state[:virtual_collision_warned] = true
+        listed = dropped.first(QUARANTINE_WARN_LIMIT)
+        more = dropped.size - listed.size
+        lines = listed.map { |name| "    - #{name}" }
+        lines << "    … and #{more} more" if more.positive?
+        warn(
+          "rigor: dropped inline-RBS contribution(s) from #{dropped.size} file(s): they declare a
+  " \
+          "constant, alias, or global that another signature source (typically the project's own
+  " \
+          "`sig/`) already declares. The explicit `.rbs` declaration wins, so inline annotations in
+  " \
+          "these files do not bind. Remove the duplication from either side to restore them:
+" \
+          "#{lines.join("\n")}"
+        )
+      end
+
+      # Records the total RBS-environment build failure captured in {#env}'s rescue so the analysis layer can
+      # surface it as the `rbs.coverage.environment-build-failed` diagnostic (the twin of
+      # {#quarantined_signatures}: quarantine keeps the env alive minus one file, a total failure collapses the
+      # WHOLE env to nil, so every type-of query degrades to `Dynamic[top]` and most rules stop firing). Stored
+      # as `[error_class_name, first_error_line, conflicting_buffer_names]`. The buffer names are lifted off a
+      # `RBS::DuplicatedDeclarationError#decls` — the typical failure, a `signature_paths:` entry redeclaring a
+      # constant/class Rigor's bundled RBS already ships — so the diagnostic can name the colliding files.
+      def record_env_build_failure(error)
+        first_line = error.message.to_s.lines.first.to_s.strip
+        @state[:env_build_failure] = [error.class.name, first_line, env_build_conflict_buffers(error)].freeze
+      end
+
+      # The buffer (file) names carried by the colliding declarations of a `RBS::DuplicatedDeclarationError`, so
+      # the diagnostic names the conflicting signature files rather than guessing. A buffer name is a `String`
+      # path for a project `signature_paths:` file and a `Pathname` for a bundled RBS file, so each is coerced
+      # to `String`. Other RBS build errors carry no `.decls`; they yield an empty list and the diagnostic
+      # falls back to the message's first line alone.
+      def env_build_conflict_buffers(error)
+        return [].freeze unless error.respond_to?(:decls)
+
+        error.decls.filter_map { |decl| decl.location&.buffer&.name }.map(&:to_s).uniq.freeze
+      rescue ::RBS::BaseError, StandardError
+        [].freeze
+      end
+
       def warn_about_env_build_failure_once(error)
         return if @state[:env_build_warned]