rigortype 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a2903b58458e4dafb9acfb05574d615031a79b8b7b521b02029bd30b07ef433
-  data.tar.gz: cf13a88ee96fe6a3acb471fb8f8936407b28bae6bd92852e8263b11ec0738870
+  metadata.gz: 0eaff9cf0ef65d44ceb3666a23fb77003a3dbb0361d890e1d2991ef6539499de
+  data.tar.gz: e7fdc58be21409504965f35479559d26bcf4726ba0feabe3fd5128bcffe8419b
 SHA512:
-  metadata.gz: 5761ae7907222592d4fd8a7c747e24f414c95fc2ce2ce2b0385a8277b0860aaa89c76c2da94b37575f3a79ac6dddbd4fd21fd16f8064ded1aecbb0e5fadb68f7
-  data.tar.gz: 8c98d8abd24b9eacef42ba5dbcade9481427a03b61c57306efb273b34ca7b2cbdc73535d3c7495aba90b13051274f9df715a6064f98e9ffb9bdbc995e573560e
+  metadata.gz: 94aae7605ca3243e7226e6f2e1c844f141d3ef04995751718e08ef5fb9dfa550455c6c87420e731332b765ee262442ed2608b5f0d7b05a25b982615b993114e5
+  data.tar.gz: f2dedba8fb33b9f7d98ddaa4debcec042edf56396c22a791ce8897736839c559240cb20158916f7c2bc5f483da06c1bebb7212ec2f24b16c3554164f849da621

data/README.md

@@ -445,19 +445,20 @@ plugin-supplied type-vocabulary resolvers, and
 [ADR-16](docs/adr/16-macro-expansion.md) macro / DSL expansion
 substrate (declarative Tier A block-as-method / Tier B
 trait-inlining-registry / Tier C heredoc-template / Tier D
-external-file inclusion). **Twenty-four worked examples** ship
-under [`examples/`](examples/) — each is a fully-shaped plugin
-gem with a runnable demo and an end-to-end integration spec.
+external-file inclusion). Production plugins ship under
+[`plugins/`](plugins/) — each is a fully-shaped plugin gem
+with a runnable demo and an end-to-end integration spec.
+Plugin-contract walkthroughs (deliberately simplified
+virtual use cases that spotlight one architectural surface
+per example) live under [`examples/`](examples/).
 
-**Plugin-contract teaching examples** (focus on a single
-extension-point):
+**Plugin-contract walkthroughs** (`examples/`, focus on a
+single extension-point):
 
 - [`rigor-deprecations`](examples/rigor-deprecations/) —
   smallest possible plugin (~80 lines); config-driven rules.
 - [`rigor-lisp-eval`](examples/rigor-lisp-eval/) — typing literal
   AST arguments at a method call.
-- [`rigor-statesman`](examples/rigor-statesman/) — two-pass DSL
-  analysis (collect declarations, then validate references).
 - [`rigor-pattern`](examples/rigor-pattern/) — plugin →
   analyzer collaboration via `Scope#type_of` and the
   literal-string carrier.
@@ -465,7 +466,13 @@ extension-point):
   tracking through arithmetic.
 - [`rigor-routes`](examples/rigor-routes/) — `Plugin::IoBoundary`
   reads under `TrustPolicy` plus cache producers.
-- [`rigor-typescript-utility-types`](examples/rigor-typescript-utility-types/)
+
+**Other production plugins for type-language extension** (`plugins/`):
+
+- [`rigor-statesman`](plugins/rigor-statesman/) — two-pass DSL
+  analysis (collect declarations, then validate references)
+  for the Statesman state-machine gem.
+- [`rigor-typescript-utility-types`](plugins/rigor-typescript-utility-types/)
   — `Plugin::TypeNodeResolver` chain wiring TS-canonical names
   (`Pick` / `Omit` / `Partial` / `Required` / `Readonly`) onto
   Rigor's shape-projection type functions.
@@ -473,16 +480,16 @@ extension-point):
 **Macro expansion substrate consumers** (ADR-16 — declarative
 manifest entries, no walker code):
 
-- [`rigor-sinatra`](examples/rigor-sinatra/) — **Tier A**
+- [`rigor-sinatra`](plugins/rigor-sinatra/) — **Tier A**
   block-as-method. Recognises Sinatra's nine class-level HTTP
   verb methods and narrows the route block's `self_type` so
   bare `params` / `redirect` / `halt` resolve through
   `Sinatra::Base`'s RBS.
-- [`rigor-dry-struct`](examples/rigor-dry-struct/) — **Tier C**
+- [`rigor-dry-struct`](plugins/rigor-dry-struct/) — **Tier C**
   heredoc-template. Synthesises a reader on every `Dry::Struct`
   subclass for each `attribute :name, T` / `attribute? :name, T`
   call.
-- [`rigor-devise`](examples/rigor-devise/) — **Tier B**
+- [`rigor-devise`](plugins/rigor-devise/) — **Tier B**
   trait-inlining registry mirroring `lib/devise/modules.rb`.
   Each `devise :strategy_a, :strategy_b` call explodes the
   included module's RBS instance methods onto the calling model
@@ -491,28 +498,30 @@ manifest entries, no walker code):
 
 **Rails ecosystem plugins** (Tier 1 + Tier 2 + Tier 3 + Sorbet):
 
-- Tier 1: [`rigor-rails-routes`](examples/rigor-rails-routes/),
-  [`rigor-rails-i18n`](examples/rigor-rails-i18n/),
-  [`rigor-actionmailer`](examples/rigor-actionmailer/),
-  [`rigor-activejob`](examples/rigor-activejob/).
-- Tier 2: [`rigor-actionpack`](examples/rigor-actionpack/)
+- Tier 1: [`rigor-rails-routes`](plugins/rigor-rails-routes/),
+  [`rigor-rails-i18n`](plugins/rigor-rails-i18n/),
+  [`rigor-actionmailer`](plugins/rigor-actionmailer/),
+  [`rigor-activejob`](plugins/rigor-activejob/).
+- Tier 2: [`rigor-actionpack`](plugins/rigor-actionpack/)
   (4 phases — routes / filters / renders / strong-params),
-  [`rigor-factorybot`](examples/rigor-factorybot/),
-  [`rigor-activerecord`](examples/rigor-activerecord/) —
+  [`rigor-factorybot`](plugins/rigor-factorybot/),
+  [`rigor-activerecord`](plugins/rigor-activerecord/) —
   publishes `:model_index` via ADR-9 for the other two
   to consume.
-- Tier 3: [`rigor-pundit`](examples/rigor-pundit/),
-  [`rigor-sidekiq`](examples/rigor-sidekiq/),
-  [`rigor-rspec`](examples/rigor-rspec/),
-  [`rigor-actioncable`](examples/rigor-actioncable/).
-- Parallel: [`rigor-sorbet`](examples/rigor-sorbet/) — ingests
+- Tier 3: [`rigor-pundit`](plugins/rigor-pundit/),
+  [`rigor-sidekiq`](plugins/rigor-sidekiq/),
+  [`rigor-rspec`](plugins/rigor-rspec/),
+  [`rigor-actioncable`](plugins/rigor-actioncable/).
+- Parallel: [`rigor-sorbet`](plugins/rigor-sorbet/) — ingests
   Sorbet `sig` / `T.let` / `T.cast` / `T.must` / `T.bind` /
   `T.assert_type!` / `T.reveal_type` / `T.absurd` and RBI
   files as type sources.
 
-[`examples/README.md`](examples/README.md) is the plugin
-authoring landing page — comparison table, recommended reading
-order, and the architectural map of which surface each example
+[`plugins/README.md`](plugins/README.md) is the production
+plugin catalogue (Rails / RSpec / dry-rb / Sorbet / etc.) and
+[`examples/README.md`](examples/README.md) is the walkthrough
+catalogue — comparison table, recommended reading order, and
+the architectural map of which surface each walkthrough
 exercises. The binding contract for the plugin API lives in
 [`docs/adr/2-extension-api.md`](docs/adr/2-extension-api.md);
 the slice-by-slice normative specs are under
@@ -568,10 +577,12 @@ while the inference surface stabilises. Forward-looking commitments
 - **DEFAULT_LIBRARIES stdlib coverage expansion** — out-of-the-box RBS classes available 1,273 → 1,427 (+154); 31 additional stdlib libraries auto-load.
 - **`is_a?(C)` lexical-nesting constant resolution** — predicate-narrowing now mirrors Ruby's `Module.nesting`-driven lookup.
 
-Twenty-four worked plugin examples now ship under
+Production plugins ship under [`plugins/`](plugins/) (Rails /
+RSpec / dry-rb / Sorbet / etc.) — see
+[`plugins/README.md`](plugins/README.md) for the catalogue.
+Plugin-contract walkthroughs ship under
 [`examples/`](examples/) — see
-[`examples/README.md`](examples/README.md) for the comparison
-table.
+[`examples/README.md`](examples/README.md).
 
 ## Contributing
 

data/lib/rigor/analysis/baseline.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Rigor
+  module Analysis
+    # ADR-22 Slice 1 — PHPStan-shaped per-project baseline.
+    #
+    # Loads `.rigor-baseline.yml`, filters a current run's
+    # diagnostic stream against the recorded buckets, and emits
+    # an `(surfaced, silenced_count)` pair for the CLI to render.
+    #
+    # Two row shapes are accepted (WD1):
+    #
+    #   # rule-ID row — bucket key (path, qualified_rule)
+    #   - file: app/models/user.rb
+    #     rule: call.undefined-method
+    #     count: 3
+    #
+    #   # message-pattern row — bucket key
+    #   #   (path, qualified_rule, message_regex)
+    #   - file: app/lib/sig.rb
+    #     rule: call.undefined-method
+    #     message: "undefined method `merge' for Array"
+    #     count: 1
+    #
+    # ## Semantics per (file, rule [, message]) bucket (WD4)
+    #
+    #   actual <= count    → ALL diagnostics in the bucket are silenced.
+    #   actual >  count    → ALL diagnostics in the bucket surface
+    #                        (not just the excess delta — the bucket
+    #                        has crossed its threshold; the team's
+    #                        review focus shifts from "which N is new"
+    #                        to "what's going on with this rule in
+    #                        this file as a whole").
+    #
+    # ## Filter pipeline position (WD6)
+    #
+    # The baseline filter runs LAST among the diagnostic-suppression
+    # layers:
+    #
+    #   emit →  `# rigor:disable` (per-line)
+    #        →  `# rigor:disable-file`
+    #        →  severity_profile re-stamp
+    #        →  baseline filter (this class)
+    #        →  output
+    #
+    # ## Loading (WD2 (b))
+    #
+    # `Baseline.load` is called by the CLI when it has resolved
+    # an explicit baseline path (from `--baseline=PATH` on the
+    # CLI or `baseline: <path>` in `.rigor.yml`). The presence
+    # of `.rigor-baseline.yml` on disk alone never triggers a
+    # load — that's the CLI / Configuration's job to enforce.
+    class Baseline
+      # The bucket key is intentionally tuple-shaped so rule-ID
+      # rows and message-pattern rows can coexist in a single
+      # multimap. `message` is `nil` for rule-ID rows; a Regexp
+      # for message-pattern rows.
+      # `count` shadows Struct#count; intentional — `count` is the
+      # PHPStan-compatible field name and we don't use the
+      # Enumerable-style `Struct#count` on Bucket instances.
+      Bucket = Struct.new(:file, :rule, :message_regex, :count, keyword_init: true) # rubocop:disable Lint/StructNewOverride
+
+      CURRENT_VERSION = 1
+
+      class << self
+        # Load a baseline file from disk. Returns `nil` when the
+        # path is nil (the caller's "no baseline configured"
+        # state). Raises {LoadError} on malformed content;
+        # callers translate to a user-facing diagnostic.
+        def load(path)
+          return nil if path.nil?
+          return new([]) unless File.exist?(path)
+
+          raw = YAML.safe_load_file(path, permitted_classes: [Symbol])
+          parse_loaded(raw, path: path)
+        end
+
+        # Build a baseline from a current run's diagnostic stream.
+        # `match_mode:` is `:rule` (default) or `:message`. The
+        # message-mode generator passes literal messages through
+        # `Regexp.escape` so generated rows never accidentally
+        # over-match on punctuation.
+        def from_diagnostics(diagnostics, match_mode: :rule)
+          raise ArgumentError, "match_mode must be :rule or :message" unless %i[rule message].include?(match_mode)
+
+          grouped = group_for_baseline(diagnostics, match_mode)
+          buckets = grouped.map do |key, entries|
+            Bucket.new(
+              file: key[0],
+              rule: key[1],
+              message_regex: key[2],
+              count: entries.size
+            )
+          end
+          new(buckets)
+        end
+
+        private
+
+        def parse_loaded(raw, path:)
+          raise LoadError, "#{path}: expected a Hash at top level, got #{raw.class}" unless raw.is_a?(Hash)
+
+          version = raw["version"]
+          unless version == CURRENT_VERSION
+            raise LoadError, "#{path}: unsupported `version: #{version.inspect}` (expected #{CURRENT_VERSION})"
+          end
+
+          rows = raw["ignored"] || []
+          raise LoadError, "#{path}: `ignored:` must be an Array" unless rows.is_a?(Array)
+
+          new(rows.each_with_index.map { |row, idx| parse_row(row, path: path, index: idx) })
+        end
+
+        def parse_row(row, path:, index:)
+          raise LoadError, "#{path}: ignored[#{index}] must be a Hash" unless row.is_a?(Hash)
+
+          file = row["file"] or raise LoadError, "#{path}: ignored[#{index}] missing `file:`"
+          rule = row["rule"] or raise LoadError, "#{path}: ignored[#{index}] missing `rule:`"
+          count = row["count"]
+          unless count.is_a?(Integer) && count.positive?
+            raise LoadError, "#{path}: ignored[#{index}] `count:` must be a positive Integer (got #{count.inspect})"
+          end
+
+          message_regex = nil
+          if (message = row["message"])
+            message_regex = compile_message_regex(message, path: path, index: index)
+          end
+
+          Bucket.new(file: file, rule: rule, message_regex: message_regex, count: count)
+        end
+
+        def compile_message_regex(source, path:, index:)
+          Regexp.new(source.to_s)
+        rescue RegexpError => e
+          raise LoadError, "#{path}: ignored[#{index}] `message:` is not a valid Regexp: #{e.message}"
+        end
+
+        # Returns Hash{[file, rule, regex_or_nil] => Array<Diagnostic>}.
+        # In message mode, each unique message gets its own bucket;
+        # in rule mode, every diagnostic for a (file, rule) pair
+        # contributes to a single bucket regardless of message.
+        def group_for_baseline(diagnostics, match_mode)
+          diagnostics.each_with_object({}) do |diag, into|
+            next if diag.qualified_rule.nil?
+            next if diag.path.nil?
+
+            key = case match_mode
+                  when :rule
+                    [diag.path, diag.qualified_rule, nil]
+                  when :message
+                    [diag.path, diag.qualified_rule, message_pattern_for(diag.message)]
+                  end
+            (into[key] ||= []) << diag
+          end
+        end
+
+        # Generates a Regexp source string for the baseline row.
+        # The string is `Regexp.escape`d so the YAML round-trip
+        # produces a regex that matches the literal message.
+        # Users hand-editing the row can replace the escaped
+        # form with a pattern.
+        def message_pattern_for(message)
+          Regexp.new(Regexp.escape(message.to_s))
+        end
+      end
+
+      class LoadError < StandardError; end
+
+      attr_reader :buckets
+
+      def initialize(buckets)
+        @buckets = buckets.freeze
+        # For each (file, qualified_rule) pair, two arrays:
+        # - rule-ID rows (message_regex == nil)
+        # - message-pattern rows (message_regex != nil)
+        # The matcher walks message-pattern rows first (tighter
+        # match takes precedence); diagnostics that don't match
+        # any message row fall through to the rule-ID row if
+        # one exists.
+        @by_pair = buckets.group_by { |b| [b.file, b.rule] }.freeze
+        freeze
+      end
+
+      # Apply the baseline filter to a diagnostic stream.
+      #
+      # Returns a 2-tuple:
+      # - `surfaced` — the diagnostics that survived the filter
+      #   (new findings + entire over-threshold buckets).
+      # - `silenced_count` — how many diagnostics the baseline
+      #   suppressed (for the WD7 stderr summary line).
+      def filter(diagnostics)
+        return [diagnostics, 0] if buckets.empty?
+
+        grouped = group_diagnostics_for_filtering(diagnostics)
+        surfaced = []
+        silenced_count = 0
+
+        grouped.each_value do |entries|
+          bucket = entries[:bucket]
+          diags = entries[:diagnostics]
+          # No matching bucket → all surface as new findings.
+          # `actual <= count` → all silenced (within threshold,
+          # WD4). `actual >  count` → all surface (over
+          # threshold, WD4).
+          if bucket && diags.size <= bucket.count
+            silenced_count += diags.size
+          else
+            surfaced.concat(diags)
+          end
+        end
+
+        # Diagnostics that lacked a rule or a path bypass the
+        # baseline entirely (the baseline can't address them).
+        unkeyable = diagnostics.reject { |d| d.qualified_rule && d.path }
+        [surfaced + unkeyable, silenced_count]
+      end
+
+      # A single bucket's drift state for slice 2 inspection.
+      # `status` is one of:
+      #
+      # - `:within`    — `actual <= count` (silenced by the filter).
+      # - `:over`      — `actual > count` (over threshold; surfaced
+      #                  in the regular `rigor check` output).
+      # - `:cleared`   — `actual == 0` (the bucket can be pruned).
+      # - `:reducible` — `0 < actual < count` (the bucket's count
+      #                  can be tightened; future `regenerate`
+      #                  slice 5 handles this).
+      DriftRow = Struct.new(:bucket, :actual_count, :status, keyword_init: true) do
+        def delta
+          actual_count - bucket.count
+        end
+      end
+
+      # Walk the current diagnostic stream and report
+      # bucket-level drift. Each baseline bucket becomes one
+      # DriftRow regardless of whether the current run still
+      # matches it.
+      #
+      # @param diagnostics [Array<Diagnostic>] current run's
+      #   diagnostic stream (PRE-filter — pass the raw
+      #   `result.diagnostics` from `Runner#run`, not the
+      #   post-baseline surface).
+      # @return [Array<DriftRow>] one entry per baseline bucket,
+      #   in baseline-file order.
+      def audit(diagnostics)
+        counts = Hash.new(0)
+        diagnostics.each do |diag|
+          next if diag.qualified_rule.nil? || diag.path.nil?
+
+          bucket = claim_bucket_for(diag)
+          counts[bucket_key(bucket)] += 1 if bucket
+        end
+
+        buckets.map do |bucket|
+          actual = counts[bucket_key(bucket)]
+          DriftRow.new(bucket: bucket, actual_count: actual, status: status_for(actual, bucket.count))
+        end
+      end
+
+      # Returns a new Baseline with the given buckets dropped.
+      # Used by `rigor baseline prune` (slice 2) to remove
+      # cleared buckets (`actual == 0`) from the on-disk file.
+      def without(buckets_to_drop)
+        dropset = buckets_to_drop.to_set
+        self.class.new(buckets.reject { |b| dropset.include?(b) })
+      end
+
+      # Serialise to a YAML string. The generator path writes
+      # this through `File.write`; the dump format is stable
+      # across versions of this class as long as the bucket
+      # shape is unchanged.
+      def to_yaml
+        rows = buckets.map do |bucket|
+          row = { "file" => bucket.file, "rule" => bucket.rule }
+          row["message"] = bucket.message_regex.source if bucket.message_regex
+          row["count"] = bucket.count
+          row
+        end
+
+        document = { "version" => CURRENT_VERSION, "ignored" => rows }
+        YAML.dump(document)
+      end
+
+      # The number of buckets recorded. Useful for the CLI
+      # summary on `generate`.
+      def size
+        buckets.size
+      end
+
+      def empty?
+        buckets.empty?
+      end
+
+      private
+
+      def status_for(actual, count)
+        return :cleared if actual.zero?
+        return :over if actual > count
+        return :within if actual == count
+
+        :reducible
+      end
+
+      def bucket_key(bucket)
+        [bucket.file, bucket.rule, bucket.message_regex&.source]
+      end
+
+      def group_diagnostics_for_filtering(diagnostics)
+        # First pass: bin each diagnostic into the bucket that
+        # claims it. Message-pattern rows take precedence over
+        # rule-ID rows because they're more specific. A
+        # diagnostic that matches no row goes into a synthetic
+        # "no-bucket" bin keyed by (file, rule).
+        bins = {}
+        diagnostics.each do |diag|
+          next if diag.qualified_rule.nil? || diag.path.nil?
+
+          bucket = claim_bucket_for(diag)
+          key = if bucket
+                  [bucket.file, bucket.rule,
+                   bucket.message_regex&.source]
+                else
+                  [diag.path, diag.qualified_rule, :__none__]
+                end
+          bin = (bins[key] ||= { bucket: bucket, diagnostics: [] })
+          bin[:diagnostics] << diag
+        end
+        bins
+      end
+
+      def claim_bucket_for(diagnostic)
+        candidates = @by_pair[[diagnostic.path, diagnostic.qualified_rule]]
+        return nil if candidates.nil? || candidates.empty?
+
+        # Tighter (message-pattern) buckets first, then the
+        # rule-ID bucket as fallback.
+        message_buckets, rule_buckets = candidates.partition(&:message_regex)
+        message_buckets.each do |b|
+          return b if b.message_regex.match?(diagnostic.message.to_s)
+        end
+        rule_buckets.first
+      end
+    end
+  end
+end

data/lib/rigor/analysis/check_rules.rb

@@ -228,10 +228,26 @@ module Rigor
       def ivar_mismatch_diagnostics_for(path, class_name, ivar_name, writes)
         return [] if writes.size < 2
 
-        first_class = ivar_class_for(writes.first[:type])
+        # Skip past leading `NilClass` writes when establishing
+        # the canonical type. The common nullable-slot idiom
+        # (`@x = nil` placeholder in `initialize` / a default
+        # state slot, then `@x = :foo` on first concrete state)
+        # would otherwise fire a false positive on every
+        # concrete write because `first_class` was `NilClass`
+        # and every subsequent `Symbol` / `String` / `Hash`
+        # write triggered the divergence rule. The first
+        # concrete (non-nil) write is the canonical type;
+        # additional `NilClass` writes are still tolerated
+        # downstream by the existing `other_class == "NilClass"`
+        # check (the nullable-slot resets to nil between work).
+        canonical = writes.find { |w| ivar_class_for(w[:type]) != "NilClass" }
+        return [] if canonical.nil?
+
+        first_class = ivar_class_for(canonical[:type])
         return [] if first_class.nil?
 
-        writes[1..].filter_map do |write|
+        canonical_index = writes.index(canonical)
+        writes[(canonical_index + 1)..].filter_map do |write|
           other_class = ivar_class_for(write[:type])
           next nil if other_class.nil? || other_class == "NilClass" || other_class == first_class
 
@@ -358,9 +374,27 @@ module Rigor
           method_def = lookup_method(receiver_type, class_name, call_node.name, scope)
           return nil if method_def
 
+          # Module-mixin fallback (mirror of
+          # `MethodDispatcher#user_class_fallback_receiver`'s module
+          # path): an instance method on a module-mixin like
+          # `PP::ObjectMixin` observes Kernel / Object methods
+          # through every concrete includer's ancestor chain, so an
+          # unresolved `self.inspect` / `self.respond_to?` /
+          # `self.class` MUST NOT fire `undefined-method`. Retry
+          # against Object before the rule fires.
+          return nil if module_mixin_receiver?(receiver_type, scope) &&
+                        lookup_method(receiver_type, "Object", call_node.name, scope)
+
           build_undefined_method_diagnostic(path, call_node, receiver_type)
         end
 
+        def module_mixin_receiver?(receiver_type, scope)
+          return false unless receiver_type.is_a?(Type::Nominal)
+          return false if scope.environment.nil?
+
+          scope.environment.rbs_module?(receiver_type.class_name)
+        end
+
         # Returns a qualified class name for the in-scope check.
         # Nominal / Singleton carry a single-class identity
         # directly. Constant projects to its value's class.
@@ -1042,8 +1076,29 @@ module Rigor
         #   (no splat / kw / block-pass / forwarded).
         # - Per-argument: skip when EITHER side is `Dynamic`
         #   (the call cannot be statically refuted).
+        # Ruby's universal-equality methods accept any object
+        # per the `Object#==(other) → bool` /
+        # `Object#eql?(other) → bool` contract. Even when a
+        # subclass overrides `==` to compare specific shapes
+        # (URI::Generic#==(URI::Generic), Time#==(Time), …),
+        # the runtime convention is to RETURN false for
+        # type-mismatched arguments rather than raise. RBS sigs
+        # that declare a tight parameter type therefore over-
+        # specify; checking arguments against them produces
+        # spurious mismatches such as
+        #   `URI::Generic#==(URI::Generic)`
+        #   called with `URI::HTTP | nil`
+        # tdiary-core's `config_uri == referer_uri` (where
+        # `referer_uri` is `URI.parse(...) if condition`, hence
+        # union-with-nil) is the canonical case. Skip arg
+        # checking on these methods entirely; the call is
+        # well-formed by Ruby's contract.
+        UNIVERSAL_EQUALITY_METHODS = %i[== != eql? equal? <=>].to_set.freeze
+        private_constant :UNIVERSAL_EQUALITY_METHODS
+
         def argument_type_diagnostic(path, call_node, scope_index)
           return nil if call_node.receiver.nil?
+          return nil if UNIVERSAL_EQUALITY_METHODS.include?(call_node.name)
           return nil unless plain_positional_call?(call_node)
 
           scope = scope_index[call_node]

data/lib/rigor/builtins/static_return_refinements.rb

@@ -53,6 +53,9 @@ module Rigor
       ).freeze
       private_constant :NON_EMPTY_STRING_OR_NIL
 
+      NON_EMPTY_STRING = Type::Combinator.non_empty_string.freeze
+      private_constant :NON_EMPTY_STRING
+
       # `Kernel#__dir__` returns the canonical directory of the
       # source file the call appears in, or `nil` when the file
       # is invalid / not available (typically `-e` and similar
@@ -62,12 +65,31 @@ module Rigor
       KERNEL_DIR = ->(_arg_types) { NON_EMPTY_STRING_OR_NIL }
       private_constant :KERNEL_DIR
 
+      # `File.expand_path(path, ?dir_string)` always returns an
+      # absolute path string. Even `File.expand_path("")` expands
+      # to the current working directory's absolute path. The
+      # upstream RBS row is `(path file_name, ?path dir_string) ->
+      # String`; the refinement tightens to `non-empty-string`.
+      #
+      # `File.dirname(path, ?level)` always returns at least `"."`
+      # (or `"/"` for absolute roots), so the return is never the
+      # empty string. Upstream RBS returns `String`; the refinement
+      # tightens to `non-empty-string`.
+      #
+      # `File.basename` is intentionally NOT refined: it returns
+      # `""` for `File.basename("")`, so `non-empty-string` would
+      # be unsound.
+      FILE_NON_EMPTY = ->(_arg_types) { NON_EMPTY_STRING }
+      private_constant :FILE_NON_EMPTY
+
       # Frozen ((owner_class_name, method_name, kind) => handler)
       # table. The kind tag is `:both`, `:singleton`, or
       # `:instance`. New entries SHOULD prefer `:both` unless the
       # singleton- and instance-side shapes genuinely differ.
       OVERRIDES = {
-        ["Kernel", :__dir__, :both] => KERNEL_DIR
+        ["Kernel", :__dir__, :both] => KERNEL_DIR,
+        ["File", :expand_path, :singleton] => FILE_NON_EMPTY,
+        ["File", :dirname, :singleton] => FILE_NON_EMPTY
       }.freeze
       private_constant :OVERRIDES