rigortype 0.1.6 → 0.1.7

data/lib/rigor/cli/baseline_command.rb

@@ -0,0 +1,377 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+require_relative "../analysis/baseline"
+require_relative "../analysis/runner"
+require_relative "../cache/store"
+require_relative "../configuration"
+
+module Rigor
+  class CLI
+    # ADR-22 Slice 1 — `rigor baseline {generate}` subcommands.
+    # Backed by `Rigor::Analysis::Baseline`. Future slices
+    # extend the subcommand surface with `dump`, `drift`,
+    # `prune`, `regenerate`.
+    #
+    # Initial subcommand: `generate`.
+    #
+    #   rigor baseline generate              # default: rule-ID rows
+    #   rigor baseline generate --match-mode message
+    #   rigor baseline generate --force      # overwrite existing
+    #   rigor baseline generate --output=PATH
+    class BaselineCommand # rubocop:disable Metrics/ClassLength
+      EXIT_USAGE = 64
+      DEFAULT_BASELINE_PATH = ".rigor-baseline.yml"
+
+      SUBCOMMANDS = %w[generate dump drift prune].freeze
+
+      def initialize(argv:, out: $stdout, err: $stderr)
+        @argv = argv
+        @out = out
+        @err = err
+      end
+
+      def run
+        subcommand = @argv.shift
+        case subcommand
+        when nil, "help", "-h", "--help"
+          @out.puts(help)
+          0
+        when "generate" then run_generate
+        when "dump" then run_dump
+        when "drift" then run_drift
+        when "prune" then run_prune
+        else
+          @err.puts("Unknown baseline subcommand: #{subcommand.inspect}")
+          @err.puts(help)
+          EXIT_USAGE
+        end
+      rescue OptionParser::ParseError => e
+        @err.puts(e.message)
+        EXIT_USAGE
+      end
+
+      private
+
+      def run_generate
+        options = parse_generate_options
+        path = options.fetch(:output)
+
+        if File.exist?(path) && !options.fetch(:force)
+          @err.puts("rigor: #{path} already exists. Re-run with --force to overwrite.")
+          return EXIT_USAGE
+        end
+
+        configuration = Configuration.load(options.fetch(:config))
+        diagnostics = collect_diagnostics(configuration, options)
+
+        baseline = Analysis::Baseline.from_diagnostics(diagnostics, match_mode: options.fetch(:match_mode))
+        File.write(path, baseline.to_yaml)
+
+        bucket_count = baseline.size
+        diagnostic_count = diagnostics.size
+        @err.puts(
+          "rigor: wrote baseline to #{path} " \
+          "(#{bucket_count} bucket(s) covering #{diagnostic_count} diagnostic(s); " \
+          "match-mode: #{options.fetch(:match_mode)})"
+        )
+        if configuration.baseline_path.nil?
+          @err.puts(
+            "rigor: note — `.rigor.yml` does not declare `baseline:`; " \
+            "add `baseline: #{path}` to activate the suppression."
+          )
+        end
+        0
+      end
+
+      def parse_generate_options
+        options = {
+          config: nil,
+          output: DEFAULT_BASELINE_PATH,
+          match_mode: :rule,
+          force: false
+        }
+        parser = OptionParser.new do |opts|
+          opts.banner = "Usage: rigor baseline generate [options]"
+          opts.on("--config=PATH", "Path to the Rigor configuration file") { |v| options[:config] = v }
+          opts.on("--output=PATH", "Write baseline to PATH (default: #{DEFAULT_BASELINE_PATH})") do |v|
+            options[:output] = v
+          end
+          opts.on("--match-mode=MODE", %i[rule message],
+                  "Row form: rule (default) or message") do |v|
+            options[:match_mode] = v
+          end
+          opts.on("--force", "Overwrite an existing baseline file") { options[:force] = true }
+        end
+        parser.parse!(@argv)
+        options
+      end
+
+      def collect_diagnostics(configuration, _options)
+        cache_store = Cache::Store.new(root: configuration.cache_path)
+        # IMPORTANT: do NOT activate the existing baseline when
+        # generating a fresh one — otherwise the new file
+        # records the post-filter (silenced) diagnostic set,
+        # which is empty after a successful first run.
+        configuration_for_generation = override_configuration_baseline_off(configuration)
+        runner = Analysis::Runner.new(
+          configuration: configuration_for_generation,
+          cache_store: cache_store,
+          collect_stats: false
+        )
+        runner.run(configuration_for_generation.paths).diagnostics
+      end
+
+      def override_configuration_baseline_off(configuration)
+        # Synthesise a new Configuration with `baseline` explicitly
+        # disabled. The original Configuration is frozen-ish so we
+        # round-trip through the constructor with an override hash.
+        defaults = Configuration::DEFAULTS.merge(
+          "paths" => configuration.paths,
+          "exclude" => configuration.exclude_patterns,
+          "plugins" => configuration.plugins.map(&:to_h),
+          "disable" => configuration.disabled_rules,
+          "libraries" => configuration.libraries,
+          "signature_paths" => configuration.signature_paths,
+          "pre_eval" => configuration.pre_eval,
+          "severity_profile" => configuration.severity_profile.to_s,
+          "severity_overrides" => configuration.severity_overrides,
+          "baseline" => false,
+          "cache" => { "path" => configuration.cache_path }
+        )
+        Configuration.new(defaults)
+      end
+
+      # ---- dump --------------------------------------------------
+
+      def run_dump
+        options = parse_dump_options
+        baseline = load_baseline_or_exit(options.fetch(:baseline))
+        return EXIT_USAGE if baseline == :error
+
+        rows = filter_dump_rows(baseline.buckets, options)
+        case options.fetch(:format)
+        when :json then @out.puts(JSON.pretty_generate(dump_to_json(rows)))
+        else dump_text(rows, options)
+        end
+        0
+      end
+
+      def parse_dump_options
+        options = { baseline: DEFAULT_BASELINE_PATH, format: :text, rule: nil, file: nil }
+        parser = OptionParser.new do |opts|
+          opts.banner = "Usage: rigor baseline dump [options]"
+          opts.on("--baseline=PATH", "Path to the baseline file (default: #{DEFAULT_BASELINE_PATH})") do |v|
+            options[:baseline] = v
+          end
+          opts.on("--format=FORMAT", %i[text json], "Output format: text (default) or json") do |v|
+            options[:format] = v
+          end
+          opts.on("--rule=RULE", "Filter rows by exact rule id") { |v| options[:rule] = v }
+          opts.on("--file=GLOB", "Filter rows by File.fnmatch? glob") { |v| options[:file] = v }
+        end
+        parser.parse!(@argv)
+        options
+      end
+
+      def filter_dump_rows(buckets, options)
+        buckets.select do |b|
+          next false if options[:rule] && b.rule != options[:rule]
+          next false if options[:file] && !File.fnmatch?(options[:file], b.file)
+
+          true
+        end
+      end
+
+      def dump_text(rows, options)
+        if rows.empty?
+          @out.puts("(no baseline rows matching the supplied filters)")
+          return
+        end
+
+        # Group by rule for readability; rules with the most
+        # entries first.
+        by_rule = rows.group_by(&:rule).sort_by { |_rule, group| -group.size }
+        by_rule.each do |rule, group|
+          total = group.sum(&:count)
+          @out.puts("#{rule}  (#{group.size} bucket(s), #{total} occurrence(s))")
+          group.sort_by { |b| [-b.count, b.file] }.each do |bucket|
+            label = if bucket.message_regex
+                      "  #{bucket.file}: #{bucket.count}  ~/#{bucket.message_regex.source}/"
+                    else
+                      "  #{bucket.file}: #{bucket.count}"
+                    end
+            @out.puts(label)
+          end
+          @out.puts("")
+        end
+        @out.puts("Total: #{rows.size} bucket(s), #{rows.sum(&:count)} occurrence(s)")
+        _ = options # reserved for future flags
+      end
+
+      def dump_to_json(rows)
+        {
+          "version" => Analysis::Baseline::CURRENT_VERSION,
+          "ignored" => rows.map do |b|
+            row = { "file" => b.file, "rule" => b.rule, "count" => b.count }
+            row["message"] = b.message_regex.source if b.message_regex
+            row
+          end
+        }
+      end
+
+      # ---- drift --------------------------------------------------
+
+      def run_drift
+        options = parse_drift_options
+        baseline = load_baseline_or_exit(options.fetch(:baseline))
+        return EXIT_USAGE if baseline == :error
+
+        configuration = Configuration.load(options.fetch(:config))
+        diagnostics = collect_diagnostics(configuration, options)
+        drift_rows = baseline.audit(diagnostics)
+
+        shown = if options.fetch(:only).nil?
+                  drift_rows.reject { |r| r.delta.zero? }
+                else
+                  drift_rows.select { |r| r.status == options.fetch(:only) }
+                end
+
+        if shown.empty?
+          @out.puts("No drift detected.")
+          return 0
+        end
+
+        report_drift_rows(shown, baseline_path: options.fetch(:baseline))
+        0
+      end
+
+      def parse_drift_options
+        options = {
+          config: nil,
+          baseline: DEFAULT_BASELINE_PATH,
+          only: nil
+        }
+        parser = OptionParser.new do |opts|
+          opts.banner = "Usage: rigor baseline drift [options]"
+          opts.on("--config=PATH", "Path to the Rigor configuration file") { |v| options[:config] = v }
+          opts.on("--baseline=PATH", "Path to the baseline file (default: #{DEFAULT_BASELINE_PATH})") do |v|
+            options[:baseline] = v
+          end
+          opts.on("--only=STATUS", %i[within over cleared reducible],
+                  "Show only buckets with the given status (within|over|cleared|reducible)") do |v|
+            options[:only] = v
+          end
+        end
+        parser.parse!(@argv)
+        options
+      end
+
+      def report_drift_rows(rows, baseline_path:) # rubocop:disable Metrics/AbcSize
+        @out.puts("Drift report against #{baseline_path}:")
+        @out.puts("")
+        groups = rows.group_by(&:status)
+        %i[over cleared reducible within].each do |status|
+          group = groups[status] || []
+          next if group.empty?
+
+          @out.puts(drift_section_header(status, group.size))
+          group.sort_by { |r| [r.bucket.file, r.bucket.rule] }.each do |row|
+            delta_str = row.delta.positive? ? "+#{row.delta}" : row.delta.to_s
+            @out.puts("  #{row.bucket.file}  [#{row.bucket.rule}]  " \
+                      "#{row.bucket.count} → #{row.actual_count}  (Δ#{delta_str})")
+          end
+          @out.puts("")
+        end
+      end
+
+      def drift_section_header(status, count)
+        case status
+        when :over then "## Over threshold (#{count}) — bucket exceeded; check the regular diagnostic output."
+        when :cleared then "## Cleared (#{count}) — `rigor baseline prune` can drop these."
+        when :reducible then "## Reducible (#{count}) — tightening opportunity; consider `regenerate` (slice 5)."
+        when :within then "## Within threshold (#{count})"
+        end
+      end
+
+      # ---- prune --------------------------------------------------
+
+      def run_prune
+        options = parse_prune_options
+        baseline = load_baseline_or_exit(options.fetch(:baseline))
+        return EXIT_USAGE if baseline == :error
+
+        configuration = Configuration.load(options.fetch(:config))
+        diagnostics = collect_diagnostics(configuration, options)
+        drift_rows = baseline.audit(diagnostics)
+        cleared = drift_rows.select { |r| r.status == :cleared }
+
+        if cleared.empty?
+          @out.puts("No cleared buckets to prune.")
+          return 0
+        end
+
+        announce_prune(cleared, options.fetch(:baseline))
+        return 0 if options.fetch(:dry_run)
+
+        pruned = baseline.without(cleared.map(&:bucket))
+        File.write(options.fetch(:baseline), pruned.to_yaml)
+        @err.puts("rigor: pruned #{cleared.size} bucket(s); baseline now has #{pruned.size} entries.")
+        0
+      end
+
+      def parse_prune_options
+        options = {
+          config: nil,
+          baseline: DEFAULT_BASELINE_PATH,
+          dry_run: false
+        }
+        parser = OptionParser.new do |opts|
+          opts.banner = "Usage: rigor baseline prune [options]"
+          opts.on("--config=PATH", "Path to the Rigor configuration file") { |v| options[:config] = v }
+          opts.on("--baseline=PATH", "Path to the baseline file (default: #{DEFAULT_BASELINE_PATH})") do |v|
+            options[:baseline] = v
+          end
+          opts.on("--dry-run", "Show what would be dropped without writing the file") { options[:dry_run] = true }
+        end
+        parser.parse!(@argv)
+        options
+      end
+
+      def announce_prune(cleared, baseline_path)
+        @out.puts("#{cleared.size} bucket(s) to prune from #{baseline_path}:")
+        cleared.sort_by { |r| [r.bucket.file, r.bucket.rule] }.each do |row|
+          @out.puts("  - #{row.bucket.file}  [#{row.bucket.rule}]  (was: #{row.bucket.count})")
+        end
+      end
+
+      # ---- shared helpers ----------------------------------------
+
+      def load_baseline_or_exit(path)
+        unless File.exist?(path)
+          @err.puts("rigor: baseline file not found: #{path}")
+          return :error
+        end
+        Analysis::Baseline.load(path)
+      rescue Analysis::Baseline::LoadError => e
+        @err.puts("rigor: baseline load failed: #{e.message}")
+        :error
+      end
+
+      def help
+        <<~HELP
+          Usage: rigor baseline <subcommand> [options]
+
+          Subcommands:
+            generate    Write a fresh baseline file from a `rigor check` run.
+            dump        Print the contents of an existing baseline.
+            drift       Compare baseline vs current diagnostics (reduction / regression hints).
+            prune       Drop cleared buckets (`actual == 0`) from the baseline.
+
+          Run `rigor baseline <subcommand> --help` for subcommand options.
+        HELP
+      end
+    end
+  end
+end

data/lib/rigor/cli.rb

@@ -26,7 +26,8 @@ module Rigor
       "explain" => :run_explain,
       "diff" => :run_diff,
       "sig-gen" => :run_sig_gen,
-      "lsp" => :run_lsp
+      "lsp" => :run_lsp,
+      "baseline" => :run_baseline
     }.freeze
 
     def self.start(argv = ARGV, out: $stdout, err: $stderr)
@@ -71,6 +72,7 @@ module Rigor
     def run_check
       require_relative "analysis/runner"
       require_relative "analysis/buffer_binding"
+      require_relative "analysis/baseline"
       require_relative "cache/store"
 
       options = parse_check_options
@@ -86,6 +88,7 @@ module Rigor
         buffer: buffer, cache_root: cache_root
       )
       result = runner.run(@argv.empty? ? configuration.paths : @argv)
+      result = apply_baseline_filter(result, configuration, options)
 
       write_result(result, options.fetch(:format))
       write_run_stats(result.stats) if result.stats
@@ -93,6 +96,51 @@ module Rigor
       result.success? ? 0 : 1
     end
 
+    # ADR-22 — apply the baseline filter as the LAST step of
+    # the diagnostic pipeline (after `# rigor:disable`,
+    # `severity_profile`, etc. — WD6). Resolution order
+    # follows WD2 (b):
+    #
+    #   1. --no-baseline on the CLI → no baseline.
+    #   2. --baseline=PATH on the CLI → load that path.
+    #   3. .rigor.yml's `baseline: <path>` → load that path.
+    #   4. otherwise → no baseline.
+    #
+    # When the path resolves and loads successfully, the filter
+    # replaces `result.diagnostics` with the surfaced set and
+    # writes a one-line summary to stderr (WD7) when any
+    # diagnostics were silenced. Load failures emit a warning
+    # to stderr and fall through to "no baseline" (graceful
+    # degradation).
+    def apply_baseline_filter(result, configuration, options)
+      path = resolve_baseline_path(configuration, options)
+      return result if path.nil?
+
+      baseline = Analysis::Baseline.load(path)
+      return result if baseline.nil?
+
+      surfaced, silenced_count = baseline.filter(result.diagnostics)
+      report_baseline_summary(silenced_count, path) if silenced_count.positive?
+      Analysis::Result.new(diagnostics: surfaced, stats: result.stats)
+    rescue Analysis::Baseline::LoadError => e
+      @err.puts("rigor: baseline load failed: #{e.message} (continuing without baseline)")
+      result
+    end
+
+    # WD2 (b) — resolve effective baseline path.
+    def resolve_baseline_path(configuration, options)
+      cli_value = options.fetch(:baseline)
+      case cli_value
+      when false then nil # --no-baseline
+      when :unset then configuration.baseline_path # fall through to config
+      else cli_value # --baseline=PATH
+      end
+    end
+
+    def report_baseline_summary(silenced_count, baseline_path)
+      @err.puts("rigor: #{silenced_count} diagnostic(s) silenced by baseline #{baseline_path}")
+    end
+
     def build_check_runner(configuration:, options:, buffer:, cache_root:)
       cache_store = options.fetch(:no_cache) ? nil : Cache::Store.new(root: cache_root)
       Analysis::Runner.new(
@@ -180,9 +228,14 @@ module Rigor
         # Both must appear together; the runner uses the pair
         # to bind an in-flight buffer file to its logical path.
         tmp_file: nil,
-        instead_of: nil
+        instead_of: nil,
+        # ADR-22 — baseline filter. `:unset` means "fall through
+        # to `.rigor.yml`'s `baseline:` key"; a String overrides
+        # the config; `false` (from `--no-baseline`) suppresses
+        # any baseline that the config might name.
+        baseline: :unset
       }
-      parser = OptionParser.new do |opts|
+      parser = OptionParser.new do |opts| # rubocop:disable Metrics/BlockLength
         opts.banner = "Usage: rigor check [options] [paths]"
         opts.on("--config=PATH", "Path to the Rigor configuration file") { |value| options[:config] = value }
         opts.on("--format=FORMAT", "Output format: text or json") { |value| options[:format] = value }
@@ -206,6 +259,14 @@ module Rigor
                 "Editor mode: the logical project path the buffer represents (paired with --tmp-file)") do |value|
           options[:instead_of] = value
         end
+        opts.on("--baseline=PATH",
+                "ADR-22: load baseline from PATH (overrides .rigor.yml `baseline:`)") do |value|
+          options[:baseline] = value
+        end
+        opts.on("--no-baseline",
+                "ADR-22: ignore any configured baseline for this run") do
+          options[:baseline] = false
+        end
       end
       parser.parse!(@argv)
       options
@@ -397,6 +458,12 @@ module Rigor
       LspCommand.new(argv: @argv, out: @out, err: @err).run
     end
 
+    def run_baseline
+      require_relative "cli/baseline_command"
+
+      BaselineCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
     def write_result(result, format)
       case format
       when "json"

data/lib/rigor/configuration.rb

@@ -59,6 +59,14 @@ module Rigor
       # the dispatcher tier consuming the registry lands in
       # slice 2.
       "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` `baseline:` declaration.
+      # The presence of `.rigor-baseline.yml` on disk alone does
+      # NOT activate filtering — the path must be named here
+      # (WD2 (b) of ADR-22).
+      "baseline" => nil,
       "fold_platform_specific_paths" => false,
       "cache" => {
         "path" => ".rigor/cache"
@@ -166,7 +174,7 @@ module Rigor
                 :dependencies, :parallel_workers,
                 :bundler_bundle_path, :bundler_auto_detect, :bundler_lockfile,
                 :rbs_collection_lockfile, :rbs_collection_auto_detect,
-                :pre_eval
+                :pre_eval, :baseline_path
 
     # Loads a configuration file.
     #
@@ -321,6 +329,7 @@ module Rigor
       @pre_eval = expand_pre_eval_entries(
         Array(data.fetch("pre_eval", DEFAULTS.fetch("pre_eval"))).map(&:to_s)
       )
+      @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
@@ -488,6 +497,17 @@ module Rigor
       raise ArgumentError, "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 (useful in
+    # `.rigor.yml` to override an upstream `.rigor.dist.yml`
+    # that names a baseline). `nil` (default / absent key) is
+    # also "no baseline".
+    def coerce_baseline_path(value)
+      return nil if value.nil? || value == false
+
+      value.to_s
+    end
+
     def coerce_network_policy(value)
       sym = value.to_sym
       unless VALID_NETWORK_POLICIES.include?(sym)

data/lib/rigor/environment/rbs_coverage_report.rb

@@ -42,7 +42,7 @@ module Rigor
       # enough that hard-coding is acceptable; a directory walk
       # at every call would add stat-cost to no benefit.)
       VENDORED_GEM_NAMES = Set[
-        "bcrypt", "idn-ruby", "mysql2", "nokogiri", "pg", "prism", "redis"
+        "bcrypt", "bundler", "cgi", "did_you_mean", "idn-ruby", "mysql2", "nokogiri", "pg", "prism", "redis", "rubygems"
       ].freeze
 
       # @param locked_gems [Hash{String => LockfileResolver::LockedGem}]

data/lib/rigor/environment/rbs_loader.rb

@@ -160,6 +160,28 @@ module Rigor
                                   end
       end
 
+      # Returns true when the named RBS declaration is a Module
+      # (`RBS::AST::Declarations::Module`) rather than a Class. The
+      # `user_class_fallback_receiver` tier consults this to route
+      # `Nominal[M].some_kernel_method` (where M is a module mixin
+      # like `PP::ObjectMixin`) through the `Nominal[Object]`
+      # fallback, because every concrete includer of M sees Kernel
+      # / Object instance methods as part of its own ancestor chain.
+      #
+      # Returns false for classes, for unknown names, and when the
+      # RBS environment failed to build (fail-soft).
+      def rbs_module?(name)
+        return false if env.nil?
+
+        rbs_name = parse_type_name(name)
+        return false if rbs_name.nil?
+
+        entry = env.class_decls[rbs_name]
+        entry.is_a?(::RBS::Environment::ModuleEntry)
+      rescue ::RBS::BaseError
+        false
+      end
+
       # Yields every known class / module / alias name (top-level
       # prefixed) currently loaded into the environment. The cache
       # producer that materialises the known-name set uses this so

data/lib/rigor/environment.rb

@@ -354,6 +354,19 @@ module Rigor
       @rbs_loader&.reflection
     end
 
+    # Returns true when the RBS environment carries the named
+    # declaration as a Module (not a Class). Used by the
+    # `user_class_fallback_receiver` tier to detect a module-mixin
+    # receiver (e.g. `PP::ObjectMixin`) so the dispatcher can route
+    # unresolved method calls through the `Nominal[Object]`
+    # fallback — every concrete includer of M honours Kernel /
+    # Object instance methods through its own ancestor chain.
+    def rbs_module?(name)
+      return false unless rbs_loader
+
+      rbs_loader.rbs_module?(name)
+    end
+
     # Compares two class/module names using analyzer-owned class data.
     # Returns `:equal`, `:subclass`, `:superclass`, `:disjoint`, or
     # `:unknown`. The static registry handles built-ins cheaply; the RBS

data/lib/rigor/flow_contribution/fact.rb

@@ -31,14 +31,20 @@ module Rigor
     #
     # ## Field set
     #
-    # - `target_kind`: `:parameter` (call-site argument) or
-    #   `:self` (receiver). Future slices may extend the set
-    #   (`:local`, `:ivar`, `:result`); the merger is agnostic
-    #   to the concrete kinds and only requires equality.
+    # - `target_kind`: `:parameter` (call-site argument), `:self`
+    #   (receiver), or `:local` (a named local in the surrounding
+    #   scope). v0.1.8 Pillar 2 Slice 1 added `:local` so plugins
+    #   recognising bespoke call shapes (`expect(x).to be_a(T)`)
+    #   can narrow a specific scope-bound local without routing
+    #   through the parameter-name lookup that requires an
+    #   authoritative RBS sig on the called method. Future slices
+    #   may extend further (`:ivar`, `:result`). The merger is
+    #   agnostic to the concrete kinds and only requires equality.
     # - `target_name`: a `Symbol`. For `:parameter` it's the
     #   declared parameter name. For `:self` it is the literal
     #   `:self` symbol so the field stays non-nil and the merge
-    #   key is well-defined.
+    #   key is well-defined. For `:local` it's the local-variable
+    #   name (e.g. `:x` for `expect(x).to be_a(T)`).
     # - `type`: a `Rigor::Type::*` (Nominal, Refined,
     #   IntegerRange, Difference, …) the fact narrows the
     #   target toward (when `negative` is false) or away from
@@ -53,7 +59,7 @@ module Rigor
     # value {Element#target} keys on, so two facts that narrow
     # the same parameter from different contribution sources
     # land in the same merge bucket.
-    FACT_VALID_TARGET_KINDS = %i[parameter self].freeze
+    FACT_VALID_TARGET_KINDS = %i[parameter self local].freeze
 
     class Fact < Data.define(:target_kind, :target_name, :type, :negative)
       def initialize(target_kind:, target_name:, type:, negative: false)
@@ -72,10 +78,14 @@ module Rigor
       end
 
       # Composite target identifier the merger keys on. `:self`
-      # for self-targeted facts; otherwise `[:parameter, name]`
-      # so two contributions that narrow the same parameter
-      # (regardless of source family) land in the same merge
-      # bucket.
+      # for self-targeted facts; otherwise `[kind, name]` so two
+      # contributions that narrow the same `(kind, name)` pair —
+      # regardless of source family — land in the same merge
+      # bucket. `:local` and `:parameter` facts that name the
+      # same symbol stay in separate buckets, which is the
+      # correct semantics: a `:local` fact narrows the surrounding
+      # scope's named local, a `:parameter` fact narrows the
+      # call-site argument matching the parameter declaration.
       def target
         target_kind == :self ? :self : [target_kind, target_name]
       end