rigortype 0.3.4 → 0.3.5

data/lib/rigor/cli/effects_renderer.rb

@@ -16,17 +16,53 @@ module Rigor
     class EffectsRenderer
       include Renderable
 
-      def initialize(out:)
+      def initialize(out:, why: false)
         @out = out
+        @why = why
       end
 
       private
 
+      # The reason block is **collapsed to a count** by default (#434). It was 86.5 % of the bytes of a
+      # 31,191-line Redmine run, and it answers a question a reader asks about one row after reading many
+      # — so `--why` expands it, and the count is what stays on the line that made them curious.
       def render_text(report)
         report.rows.each do |row|
-          @out.puts("#{row.key}: [#{row.effects.join(', ')}]#{declared(row)}#{' …?' unless row.exhaustive?}")
+          @out.puts("#{row.key}: [#{row.effects.join(', ')}]#{declared(row)}#{hedge(row)}")
+          next unless @why
+
           row.causes.each { |cause, detail| @out.puts("    #{cause}#{" (#{detail})" if detail}") }
+          row.attribution.each { |origin, labels| @out.puts("    #{origin} → [#{labels.join(', ')}]") }
         end
+        render_footer(report.totals)
+      end
+
+      def hedge(row)
+        return "" if row.exhaustive?
+        return " …?" if @why || row.causes.empty?
+
+        " …? (#{row.causes.length} #{row.causes.length == 1 ? 'reason' : 'reasons'}, --why)"
+      end
+
+      # The footer a 31,191-line report never had, and the reason it counts the two lanes apart: a
+      # declared label can never fail a build (ADR-103 § WD17), so a reader who sees one total cannot tell
+      # which half of the report is a policy surface and which half is a record to review the diff of.
+      def render_footer(totals)
+        return if totals.nil?
+
+        @out.puts("──")
+        @out.puts("#{totals.printed} of #{totals.units} units printed#{omitted(totals)}")
+        @out.puts("#{totals.proven} carry a proven label · #{totals.declared} carry a declared (≤) one " \
+                  "· #{totals.exhaustive} are exhaustive")
+      end
+
+      # Two ways a row can be missing, counted apart because `--full` answers only one of them.
+      def omitted(totals)
+        parts = []
+        parts << "#{totals.omitted} omitted (--full)" if totals.omitted.positive?
+        parts << "#{totals.unselected} not selected" if totals.unselected.positive?
+        parts << "#{totals.truncated} cut by --limit" if totals.truncated.positive?
+        parts.empty? ? "" : "; #{parts.join(', ')}"
       end
 
       # `≤` is the lane's spelling everywhere in the model — an upper bound, not an observation — so the
@@ -43,10 +79,12 @@ module Rigor
               "declared" => row.declared,
               "exhaustive" => row.exhaustive?,
               "causes" => row.causes.map { |cause, detail| [cause, detail] },
-              "direct" => row.direct
+              "direct" => row.direct,
+              "attribution" => row.attribution
             }]
           end
         }
+        payload["totals"] = report.totals.to_h.transform_keys(&:to_s) if report.totals
         @out.puts(JSON.pretty_generate(payload))
       end
     end

data/lib/rigor/cli/effects_report.rb

@@ -7,7 +7,12 @@ module Rigor
     #
     # Rows are sorted by key and every collection inside one is sorted, so two runs over the same tree
     # print byte-identical output whether analysis ran sequentially or across the fork pool.
-    class EffectsReport < Data.define(:rows, :full)
+    class EffectsReport < Data.define(:rows, :full, :totals)
+      # `totals:` defaults so a caller that builds a report by hand keeps working.
+      def initialize(totals: nil, **rest)
+        super
+      end
+
       # One method's line in the report.
       #
       # `effects` is the transitive proven lane — this method's labels joined with every project method it
@@ -20,18 +25,116 @@ module Rigor
       # is printed apart from `effects` and never folded into it, because the two answer different
       # questions: one is proven, the other is asserted. A declared label the proven lane already admits
       # is dropped here, where output is rendered; the table keeps both lanes raw.
-      class Row < Data.define(:key, :effects, :declared, :exhaustive, :causes, :direct)
+      class Row < Data.define(:key, :effects, :declared, :exhaustive, :causes, :direct, :attribution)
+        # `attribution:` defaults so a caller that builds a row by hand keeps working.
+        def initialize(attribution: {}, **rest)
+          super
+        end
+
         def exhaustive?
           exhaustive
         end
+
+        # The reading `--pure` selects and the default report omits: nothing proven beyond what every
+        # envelope tolerates, nothing claimed, and no "possibly more".
+        def pure?
+          exhaustive && declared.empty? && (effects - TRIVIAL).empty?
+        end
+
+        # `mutate.local` is mutation of objects the frame allocated and never let out, which every
+        # envelope tolerates — so a method proving only it is what `%a{pure}` means here.
+        TRIVIAL = ["mutate.local"].freeze
+        private_constant :TRIVIAL
+
+        def carries_label?(labels)
+          labels.any? { |label| (effects + declared).any? { |own| own == label || own.start_with?("#{label}.") } }
+        end
       end
 
+      # The counts the footer prints and the JSON payload carries (#434). The two lanes are counted
+      # **separately** and deliberately: a declared label can never fail a build ([ADR-103](../adr/103-effect-labels.md)
+      # § WD17), and on a Rails application it is most of the mass — 709 `io.db.read` plus 644
+      # `io.db.write` on Redmine's 4,234 rows against zero of either proven. A single total tells a reader
+      # how big the report is; the split tells them which half is a policy surface and which half is a
+      # record whose diff they should be reviewing instead.
+      Totals = Data.define(:units, :printed, :omitted, :unselected, :proven, :declared, :exhaustive,
+                           :truncated)
+
       # Builds a report from an effect table. `full:` keeps the rows the report otherwise omits — an
       # exhaustive method proving nothing beyond `mutate.local`, which is the reading of `%a{pure}`.
-      def self.build(table, full: false)
-        rows = table.filter_map { |entry| row_for(entry) unless !full && entry.trivial? }
-        new(rows: rows.freeze, full: full)
+      #
+      # `scope:` selects which units are **printed** and never which are analysed (#439). A path argument
+      # used to narrow the analysis, and a summary is transitive over whatever was analysed, so the
+      # narrowed run answered `[] …?` for a method the whole-project run answered four labels for — with
+      # nothing distinguishing that from a method which genuinely does nothing. `sources:` is
+      # `Runner#effect_sources`, `{ "Class#m" => [path, …] }`, which is how a key is traced back to the
+      # file it was written in.
+      def self.build(table, full: false, sources: nil, scope: [], label: [], pure: false, limit: nil)
+        roots = normalize_scope(scope)
+        in_scope = table.filter_map do |entry|
+          row_for(entry) if roots.empty? || in_scope?(entry.key, sources, roots)
+        end
+        selected = in_scope.select { |row| keep?(row, full: full, label: label, pure: pure) }
+        new(rows: (limit ? selected.first(limit) : selected).freeze, full: full,
+            totals: totals_for(table, in_scope, selected, limit, query: pure || !label.empty?))
+      end
+
+      # What the default report drops, and why each is a separate question:
+      #
+      # - **`full:`** keeps a row the omission rule would drop. Two shapes qualify: a method proving
+      #   nothing beyond `mutate.local` and claiming nothing (the reading of `%a{pure}`), and a row with
+      #   no label in **either** lane, which is 35–38 % of a real application's rows and says literally
+      #   nothing — it exists only to record that something was unresolved, which the footer counts.
+      # - **`pure:`** is the complement of the first: exactly the rows the default omits for being
+      #   provably harmless, which is the set worth annotating and which nothing could ask for (#457).
+      # - **`label:`** is the question chapter 19 opens with. It matches **either** lane, because "which
+      #   controllers reach the network" is a question about the code and not about which lane knows it;
+      #   the row's own rendering keeps the two apart.
+      def self.keep?(row, full:, label:, pure:)
+        return row.pure? if pure
+        return row.carries_label?(label) unless label.empty?
+        return true if full
+
+        !row.pure? && !(row.effects.empty? && row.declared.empty?)
+      end
+      private_class_method :keep?
+
+      # Two ways a row can be missing, and only one of them `--full` answers: the **omission rule** drops
+      # a row that says nothing, and a **filter** — a path, `--label`, `--pure` — drops one that did not
+      # match. Telling a `--label io.net` reader that 4,678 more are behind `--full` would be false, so
+      # the two are counted apart.
+      def self.totals_for(table, in_scope, selected, limit, query:)
+        omitted = query ? 0 : in_scope.length - selected.length
+        Totals.new(
+          units: table.size, printed: limit ? [selected.length, limit].min : selected.length,
+          omitted: omitted, unselected: table.size - selected.length - omitted,
+          proven: selected.count { |row| !row.effects.empty? },
+          declared: selected.count { |row| !row.declared.empty? },
+          exhaustive: selected.count(&:exhaustive?),
+          truncated: limit ? [selected.length - limit, 0].max : 0
+        )
+      end
+      private_class_method :totals_for
+
+      # A path argument may name a file or a directory, and either may be written relative or absolute —
+      # so both sides are expanded and a directory matches by prefix. Deliberately not the `reach:` glob
+      # syntax: this is the argument a shell just tab-completed, and `rigor effects app/models` meaning
+      # "that directory" is the only reading a reader would guess.
+      def self.normalize_scope(scope)
+        Array(scope).map { |path| File.expand_path(path.to_s.chomp("/")) }.freeze
+      end
+      private_class_method :normalize_scope
+
+      def self.in_scope?(key, sources, roots)
+        paths = sources && sources[key]
+        return false if paths.nil? || paths.empty?
+
+        paths.any? do |path|
+          absolute = File.expand_path(path)
+          roots.any? { |root| absolute == root || absolute.start_with?("#{root}/") }
+        end
       end
+      private_class_method :in_scope?
 
       def self.row_for(entry)
         Row.new(
@@ -40,7 +143,14 @@ module Rigor
           declared: entry.rendered_declared.to_a,
           exhaustive: entry.exhaustive?,
           causes: entry.causes,
-          direct: entry.direct.bundles.to_h { |origin, labels| [origin.to_s, labels.to_a] }.freeze
+          direct: entry.direct.bundles.to_h { |origin, labels| [origin.to_s, labels.to_a] }.freeze,
+          # The declared lane's provenance (#434). A *discharging* plugin row leaves no cause line by
+          # design — WD6: a row the engine bundles is trusted, so it does not taint — which is why
+          # `plugin-attribution` appeared zero times in a whole Redmine run while 1,320 rows carried a
+          # `≤` clause. The origins are where the answer actually lives, and this is the direct half; a
+          # label that arrived transitively is `rigor effects explain`'s question.
+          attribution: entry.direct.declared_bundles.to_h { |origin, labels| [origin.to_s, labels.to_a] }
+                            .freeze
         )
       end
       private_class_method :row_for

data/lib/rigor/cli/effects_snapshot_command.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
+require "did_you_mean"
 require "optionparser"
 
 require_relative "../analysis/runner"
 require_relative "../cache/store"
 require_relative "../configuration"
 require_relative "../effects/discharge"
+require_relative "../effects/entry_points"
 require_relative "../effects/path_finder"
 require_relative "../effects/snapshot"
 require_relative "../effects/snapshot_diff"
@@ -79,8 +81,14 @@ module Rigor
         File.write(path, snapshot.to_yaml)
         @err.puts("rigor: wrote #{path} (#{snapshot.methods.size} method(s), #{snapshot.reach.size} reach entr" \
                   "#{snapshot.reach.size == 1 ? 'y' : 'ies'})")
-        @err.puts("rigor: note — `effects.snapshot.reach:` is empty, so the snapshot records `methods:` only.") if
-          configuration.effects_snapshot_reach.empty?
+        # #436 — the note names what to write, not only what is missing: the same per-project preset
+        # enumeration the unregistered-preset error uses, so the two can never disagree about which
+        # names this project's plugin set makes available.
+        if configuration.effects_snapshot_reach.empty?
+          @err.puts("rigor: note — `effects.snapshot.reach:` is empty, so the snapshot records `methods:` " \
+                    "only — the direct half. Name your entry points to record what they cause: " \
+                    "#{Effects::EntryPoints.availability}. The written file carries the same hint.")
+        end
         0
       end
 
@@ -126,20 +134,31 @@ module Rigor
 
       def explain(diff, options)
         rows = options.fetch(:symbol) ? rows_for_symbol(options.fetch(:symbol)) : rows_for_changes(diff)
+        return CLI::EXIT_USAGE if rows == :unknown
+
         EffectsExplainRenderer.new(out: @out).render(rows, format: options.fetch(:format))
         0
       end
 
+      # A misspelled `--symbol` used to print `Nothing to explain.` and exit 0, which is exactly what a
+      # method with no effects prints — so a typo and a real answer were indistinguishable, and a script
+      # could not tell them apart at all (#435). It is a usage error now, with the nearest key offered:
+      # the key set is right there, and a method key is long enough to get wrong.
       def rows_for_symbol(symbol)
         entry = @table[symbol]
         if entry.nil?
-          @err.puts("rigor: no effect unit named #{symbol}")
-          return []
+          @err.puts("rigor: no effect unit named #{symbol}#{suggestion(symbol)}")
+          return :unknown
         end
 
         reach_rows(symbol, entry.proven.to_a) + method_rows(symbol, entry.direct.proven.to_a)
       end
 
+      def suggestion(symbol)
+        nearest = ::DidYouMean::SpellChecker.new(dictionary: @table.keys).correct(symbol).first
+        nearest ? " — did you mean #{nearest}?" : ""
+      end
+
       # Every label a change introduced, explained once: a `reach:` change gets its shortest edge path, a
       # `methods:` change gets the origin in the method's own body.
       def rows_for_changes(diff)

data/lib/rigor/cli.rb

@@ -84,6 +84,17 @@ module Rigor
     rescue OptionParser::ParseError => e
       @err.puts(e.message)
       EXIT_USAGE
+    rescue ConfigurationError => e
+      # #433 — a mistake in `.rigor.yml` is the same kind of event as a bad flag, and belongs in the same
+      # shape: one `rigor:` line naming the key, and the conventional usage exit code. It used to escape
+      # as an uncaught exception with a ~30-frame backtrace naming a file inside `lib/rigor/`, which reads
+      # as a crash even though the message it carried said exactly which key to fix.
+      #
+      # Caught here rather than per command because every command loads a configuration, and the ones
+      # that resolve a key later (`effects update` expanding `snapshot.reach:` once the plugins that
+      # register presets have loaded) would each need their own rescue at their own point.
+      @err.puts("rigor: #{e.message}")
+      EXIT_USAGE
     end
 
     private
@@ -160,7 +171,7 @@ module Rigor
         # - paths:       directories scanned by `rigor check` and
         #                `rigor type-scan` when no path is given.
         # - plugins:     opt-in list of plugin gem names to load.
-        #                See https://github.com/rigortype/rigor/tree/main/plugins
+        #                See https://github.com/rigortype/rigor/tree/master/plugins
         #                for production plugins (rigor-activerecord, rigor-sorbet, …).
         # - disable:     list of `rigor check` rule identifiers to
         #                silence project-wide. The shipped rules are

data/lib/rigor/configuration.rb

@@ -6,6 +6,7 @@ require_relative "bleeding_edge"
 require_relative "ci_detector"
 require_relative "configuration/dependencies"
 require_relative "configuration/severity_profile"
+require_relative "configuration_error"
 require_relative "effects/entry_points"
 require_relative "effects/label"
 require_relative "effects/method_key"
@@ -358,10 +359,10 @@ module Rigor
     # {CLI::CheckCommand#load_check_configuration}).
     def self.load_with_includes(path, visited: Set.new)
       absolute = File.expand_path(path)
-      raise ArgumentError, "circular include: #{absolute}" if visited.include?(absolute)
+      raise ConfigurationError, "circular include: #{absolute}" if visited.include?(absolute)
 
-      raw = YAML.safe_load_file(absolute, aliases: false) || {}
-      raise ArgumentError, "config file must be a YAML mapping: #{absolute}" unless raw.is_a?(Hash)
+      raw = read_yaml(absolute)
+      raise ConfigurationError, "config file must be a YAML mapping: #{absolute}" unless raw.is_a?(Hash)
 
       base_dir = File.dirname(absolute)
       includes = Array(raw.delete("includes") || [])
@@ -370,6 +371,17 @@ module Rigor
       merge_includes(data, includes, base_dir, next_visited)
     end
 
+    # #433's sibling: a typo in the file the user is about to be told to fix is a configuration mistake
+    # like any other, and escaped as a `Psych::SyntaxError` backtrace naming a file inside Ruby's stdlib.
+    # Psych's own `#message` embeds the path in a parenthesised prefix that reads badly after `rigor: `,
+    # so the position is re-rendered in the `path:line:column` form the rest of Rigor's output uses.
+    def self.read_yaml(absolute)
+      YAML.safe_load_file(absolute, aliases: false) || {}
+    rescue Psych::SyntaxError => e
+      detail = [e.problem, e.context].compact.join(" ")
+      raise ConfigurationError, "#{absolute}:#{e.line}:#{e.column}: not valid YAML: #{detail}"
+    end
+
     def self.merge_includes(data, includes, base_dir, visited)
       return data if includes.empty?
 
@@ -377,7 +389,7 @@ module Rigor
       includes.each do |inc|
         inc_path = File.expand_path(inc.to_s, base_dir)
         unless File.exist?(inc_path)
-          raise ArgumentError, "include not found: #{inc.inspect} (referenced from #{base_dir})"
+          raise ConfigurationError, "include not found: #{inc.inspect} (referenced from #{base_dir})"
         end
 
         accumulated = deep_merge(accumulated, load_with_includes(inc_path, visited: visited))
@@ -737,7 +749,7 @@ module Rigor
 
       gate = value.to_s.to_sym
       unless VALID_EFFECTS_GATES.include?(gate)
-        raise ArgumentError,
+        raise ConfigurationError,
               "effects.snapshot.gate must be one of #{VALID_EFFECTS_GATES.inspect}, got #{value.inspect}"
       end
 
@@ -756,7 +768,7 @@ module Rigor
       entries.each do |entry|
         next if Effects::EntryPoints.glob?(entry) || Effects::EntryPoints.name?(entry)
 
-        raise ArgumentError,
+        raise ConfigurationError,
               "effects.snapshot.reach entry is neither a file glob nor a well-formed entry-point preset " \
               "name: #{entry.inspect} (a preset name is #{Effects::EntryPoints::NAME_PATTERN.inspect}; " \
               "anything carrying a path or glob character is treated as a file glob instead)"
@@ -768,7 +780,7 @@ module Rigor
     def coerce_effects_tolerated(value)
       labels = Array(value).map(&:to_s)
       labels.each do |label|
-        raise ArgumentError, "effects.tolerated is not a well-formed effect label: #{label.inspect}" unless
+        raise ConfigurationError, "effects.tolerated is not a well-formed effect label: #{label.inspect}" unless
           Effects::Label.valid?(label)
       end
       labels.uniq.sort.freeze
@@ -795,7 +807,7 @@ module Rigor
     def coerce_effects_labels(value)
       labels = Array(value).map(&:to_s)
       labels.each do |label|
-        raise ArgumentError, "effects.labels is not a well-formed effect label: #{label.inspect}" unless
+        raise ConfigurationError, "effects.labels is not a well-formed effect label: #{label.inspect}" unless
           Effects::Label.valid?(label)
       end
       labels.uniq.sort.freeze
@@ -809,7 +821,7 @@ module Rigor
       value.each_with_object({}) do |(key, labels), out|
         name = key.to_s
         unless Effects::MethodKey.valid?(name)
-          raise ArgumentError,
+          raise ConfigurationError,
                 "effects.attribution key is not a method key (`Owner#method` / `Owner.method`): #{name.inspect}"
         end
 
@@ -826,16 +838,16 @@ module Rigor
 
     def coerce_effects_envelope(entry, index)
       where = "effects.envelopes[#{index}]"
-      raise ArgumentError, "#{where} is not a mapping: #{entry.inspect}" unless entry.is_a?(Hash)
+      raise ConfigurationError, "#{where} is not a mapping: #{entry.inspect}" unless entry.is_a?(Hash)
 
       match = coerce_effects_envelope_selector(entry["match"], "#{where}.match")
       namespace = coerce_effects_envelope_selector(entry["namespace"], "#{where}.namespace")
       if match.nil? == namespace.nil?
-        raise ArgumentError, "#{where} must name exactly one of `match:` (a path glob) or `namespace:` " \
-                             "(a constant glob), got #{match.nil? ? 'neither' : 'both'}"
+        raise ConfigurationError, "#{where} must name exactly one of `match:` (a path glob) or `namespace:` " \
+                                  "(a constant glob), got #{match.nil? ? 'neither' : 'both'}"
       end
       unless entry.key?("effect")
-        raise ArgumentError, "#{where} has no `effect:` bound (write `effect: []` for the empty envelope)"
+        raise ConfigurationError, "#{where} has no `effect:` bound (write `effect: []` for the empty envelope)"
       end
 
       {
@@ -848,14 +860,14 @@ module Rigor
       return nil if value.nil?
 
       selector = value.to_s
-      raise ArgumentError, "#{where} is empty" if selector.strip.empty?
+      raise ConfigurationError, "#{where} is empty" if selector.strip.empty?
 
       selector.freeze
     end
 
     def coerce_effect_label_list(labels, where)
       labels.map(&:to_s).each do |label|
-        raise ArgumentError, "#{where} is not a well-formed effect label: #{label.inspect}" unless
+        raise ConfigurationError, "#{where} is not a well-formed effect label: #{label.inspect}" unless
           Effects::Label.valid?(label)
       end.uniq.sort.freeze
     end
@@ -886,7 +898,7 @@ module Rigor
       when Hash
         entry.to_h { |k, v| [k.to_s, v] }.freeze
       else
-        raise ArgumentError,
+        raise ConfigurationError,
               "plugin configuration entry must be a String or Hash, got #{entry.inspect}"
       end
     end
@@ -903,7 +915,7 @@ module Rigor
     def coerce_target_ruby(value)
       s = value.to_s
       unless s.match?(TARGET_RUBY_FORMAT)
-        raise ArgumentError,
+        raise ConfigurationError,
               "target_ruby must be a version (e.g. \"3.4\", \"4.0\", \"3.4.0\") or \"latest\", got #{value.inspect}"
       end
 
@@ -924,11 +936,11 @@ module Rigor
     # disabling parallelism.
     def coerce_parallel_workers(value)
       integer = Integer(value)
-      raise ArgumentError, "parallel.workers must be >= 0, got #{value.inspect}" if integer.negative?
+      raise ConfigurationError, "parallel.workers must be >= 0, got #{value.inspect}" if integer.negative?
 
       integer
     rescue TypeError, ArgumentError => e
-      raise ArgumentError, "parallel.workers must be a non-negative Integer, got #{value.inspect} (#{e.message})"
+      raise ConfigurationError, "parallel.workers must be a non-negative Integer, got #{value.inspect} (#{e.message})"
     end
 
     # ADR-22 WD2 (b) — `baseline: <path>` activates the file; `baseline: false` is the explicit-disable form
@@ -955,7 +967,7 @@ module Rigor
     def coerce_network_policy(value)
       sym = value.to_sym
       unless VALID_NETWORK_POLICIES.include?(sym)
-        raise ArgumentError,
+        raise ConfigurationError,
               "plugins_io.network must be one of #{VALID_NETWORK_POLICIES.inspect}, got #{value.inspect}"
       end
 
@@ -967,7 +979,7 @@ module Rigor
     def coerce_severity_profile(value)
       sym = value.to_sym
       unless SeverityProfile::VALID_PROFILES.include?(sym)
-        raise ArgumentError,
+        raise ConfigurationError,
               "severity_profile must be one of " \
               "#{SeverityProfile::VALID_PROFILES.inspect}, got #{value.inspect}"
       end
@@ -980,7 +992,7 @@ module Rigor
     # {SeverityProfile::VALID_SEVERITIES} symbols (`:error` / `:warning` / `:info` / `:off`). Unknown
     # severities raise; unknown rule ids are silently kept (the override is inert until the rule lands).
     def coerce_severity_overrides(value)
-      raise ArgumentError, "severity_overrides must be a Hash, got #{value.inspect}" unless value.is_a?(Hash)
+      raise ConfigurationError, "severity_overrides must be a Hash, got #{value.inspect}" unless value.is_a?(Hash)
 
       value.to_h do |k, v|
         # YAML 1.1 parses bare `off`/`on`/`no`/`yes`/`true`/`false` as booleans, so a user who wrote `off` (a
@@ -988,7 +1000,7 @@ module Rigor
         # `to_sym` blows up with a backtrace.
         unless v.is_a?(String) || v.is_a?(Symbol)
           hint = v == false ? %( — did you mean the string "off"?) : ""
-          raise ArgumentError,
+          raise ConfigurationError,
                 "severity_overrides[#{k.inspect}] is #{v.inspect}, a YAML boolean#{hint} " \
                 "Bare off/on/no/yes/true/false are parsed as booleans; quote the severity " \
                 "(e.g. \"off\")."
@@ -996,7 +1008,7 @@ module Rigor
 
         sym = v.to_sym
         unless SeverityProfile::VALID_SEVERITIES.include?(sym)
-          raise ArgumentError,
+          raise ConfigurationError,
                 "severity_overrides[#{k.inspect}] must be one of " \
                 "#{SeverityProfile::VALID_SEVERITIES.inspect}, got #{v.inspect}"
         end
@@ -1016,7 +1028,7 @@ module Rigor
       when Array then { "mode" => "list", "ids" => freeze_ids(value) }
       when Hash then coerce_bleeding_edge_hash(value)
       else
-        raise ArgumentError,
+        raise ConfigurationError,
               "bleeding_edge must be true, false, a list of feature ids, " \
               "or { all: true, except: [...] }, got #{value.inspect}"
       end.freeze

data/lib/rigor/configuration_error.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Rigor
+  # A mistake in the project's configuration — a value `Configuration` cannot proceed on (the tier-2
+  # failures `docs/internal-spec/config.md` enumerates), or a `.rigor.yml` key the loader accepted whose
+  # meaning only resolves later, like an `effects.snapshot.reach:` preset name.
+  #
+  # It exists so the CLI can tell **the user got the file wrong** apart from **Rigor got itself wrong**.
+  # Both used to reach the terminal as an uncaught `ArgumentError` with a thirty-frame backtrace naming a
+  # file inside `lib/rigor/`, which reads as a crash: the reader's first move is to file a bug, not to
+  # fix the key the message already named (#433). {CLI#run} rescues this class and renders it as a single
+  # `rigor:` line.
+  #
+  # It stays an `ArgumentError` subclass deliberately. `Configuration` raised `ArgumentError` from every
+  # coercion since the beginning, that is the documented tier-2 contract, and callers outside the CLI —
+  # the language server, embedders, the suite — rescue it by that name. Narrowing the class is a
+  # presentation change, not a contract change.
+  class ConfigurationError < ArgumentError
+  end
+end

data/lib/rigor/effects/collector.rb

@@ -128,7 +128,7 @@ module Rigor
         # {Accumulator#record} is what stops it paying for the `Data` and the origin lookup below.
         return if accumulator.recorded?(node)
 
-        dynamic = receiver.is_a?(Type::Dynamic)
+        dynamic = dynamic_receiver?(receiver)
         class_name, kind = descriptor_for(receiver)
         accumulator.record(
           node,
@@ -160,9 +160,46 @@ module Rigor
         when Type::HashShape then ["Hash", :instance]
         when Type::Constant then [receiver.value.class.name, :instance]
         when Type::Dynamic then descriptor_for(receiver.static_facet)
+        when Type::Union then union_descriptor(receiver)
         end
       end
 
+      # Whether the typer's verdict on this receiver leaves its class a guess. A bare `Dynamic` is the
+      # original case; a union carrying a `Dynamic` arm is the same knowledge in a different shape, and
+      # before #455 it was the shape that said nothing — no class, no edge, and no taint, so the summary
+      # read *exhaustive* while an arm of its receiver was admittedly unknown.
+      def dynamic_receiver?(receiver)
+        return true if receiver.is_a?(Type::Dynamic)
+
+        receiver.is_a?(Type::Union) && receiver.members.any?(Type::Dynamic)
+      end
+
+      # A union projects to a class exactly when its non-nil arms all project to the SAME one (#455).
+      #
+      # `T?` is the case that pays, and it is not a corner: ADR-58 contributes a declaration-sourced
+      # `nil` to every instance variable not written in `initialize`, so **every cross-method ivar read
+      # is a union** — `@group.save` reads `Group | nil` where the same `Group.new.save` two lines up
+      # reads `Group`. Without this arm the receiver had no class, so the plugin row never matched, the
+      # edge was dropped, and the site contributed nothing *while the summary still read exhaustive*.
+      # Whether the nil arm means the call happens at all is a question for `possible-nil-receiver`; it
+      # says nothing about what the call does when it does happen, which is the only question here.
+      #
+      # Arms that disagree (`File | StringIO`) still project to nothing. Answering with either one would
+      # state an effect no single execution need perform, and answering with both is a shape the record
+      # has no room for — one call site carries one receiver class.
+      def union_descriptor(receiver)
+        descriptors = receiver.members.reject { |member| nil_member?(member) }.map { |member| descriptor_for(member) }
+        first = descriptors.first
+        return nil if first.nil?
+
+        descriptors.all? { |descriptor| descriptor == first } ? first : nil
+      end
+
+      def nil_member?(member)
+        (member.is_a?(Type::Constant) && member.value.nil?) ||
+          (member.is_a?(Type::Nominal) && member.class_name == "NilClass")
+      end
+
       # Fail-soft (WD13): the scan raising drops this file's summaries and never reaches `rigor check`.
       def build(accumulator)
         return FileCollection.empty(accumulator.path) if accumulator.root.nil?