rigortype 0.4.7 → 0.4.8

data/lib/rigor/analysis/check_rules/plugin_api_surface.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../../configuration/severity_profile"
+require_relative "../../reflection"
+require_relative "../../source/node_walker"
+require_relative "../../scope/resolution_chain"
+require_relative "../../type"
+require_relative "../diagnostic"
+require_relative "rule_ids"
+
+module Rigor
+  module Analysis
+    module CheckRules
+      # ADR-128 WD6 / ADR-130 WD3 — `plugin.api-surface`. A call in plugin source on a value typed by a
+      # `Rigor::Plugin` interface (`Dynamic[Rigor::Plugin::_Scope]`, ...) to a member that interface does not
+      # declare. The method exists on the backing engine class, so the call works today; it is outside what Rigor
+      # promises to keep, so `call.undefined-method` would be wrong and this rule says that instead.
+      #
+      # Authored `:warning`, resolved `:off` by every profile and promoted only by the `plugin-api-surface`
+      # bleeding-edge feature (ADR-50 Decision 3, WD2), as `static.value-use.void` is.
+      #
+      # It fires only where all of these hold:
+      #
+      # - the call has an explicit receiver, typed `Dynamic[<Rigor::Plugin interface>]`, or that plus `nil` (the
+      #   facet survives only where ADR-130 WD1 keeps it; a value that lost it at a join reads `Dynamic[top]`);
+      # - the interface declares no member of the name, and `Object` (with `Kernel` and `BasicObject`) declares
+      #   none either: `nil?`, `respond_to?` and `is_a?` are every object's surface, not the engine's;
+      # - the call sits lexically inside a class whose discovered superclass chain reaches `Rigor::Plugin::Base`.
+      #   `Base` itself is not such a class, so its own hooks, which hand interface values to engine helpers
+      #   (`environment.class_ordering`), are not judged: they are engine code.
+      #
+      # The plugin-source test reads the class declarations, not a path: a third-party plugin gem keeps its plugin
+      # under `lib/` as Rigor's own engine does.
+      #
+      # The rule runs only when its resolved severity is not `:off` ({.active?}): the runner then adds its
+      # {Collector} to the shared {RuleWalk}. A default run builds no collector, so it types no extra receiver and
+      # files no ADR-46 dependency for the rule.
+      module PluginApiSurface
+        PLUGIN_BASE = "Rigor::Plugin::Base"
+
+        # One call the rule reports: the call and the first interface its receiver carries.
+        Result = Data.define(:call_node, :interface)
+
+        # The {RuleWalk} collector: one {Result} per reported call, in walk order.
+        class Collector
+          NODE_CLASSES = [Prism::CallNode].freeze
+
+          def initialize(scope_index)
+            @scope_index = scope_index
+            @results = []
+          end
+
+          # The legacy single-collector walk, the oracle the ADR-53 equivalence harness compares {RuleWalk} with.
+          def collect(root)
+            Source::NodeWalker.each(root) { |node| visit(node) if node.is_a?(Prism::CallNode) }
+            @results.freeze
+          end
+
+          def visit(node, _context = nil)
+            interface = PluginApiSurface.outside_interface(node, @scope_index[node])
+            @results << Result.new(call_node: node, interface: interface) if interface
+          end
+
+          def results
+            @results.freeze
+          end
+        end
+
+        module_function
+
+        # Whether the rule can report in a run under `configuration`: it is not in `disable:`, and its resolved
+        # severity is not `:off`. Default profiles resolve it `:off`; the `plugin-api-surface` bleeding-edge feature
+        # or an explicit `severity_overrides:` entry for the id turns it on.
+        def active?(configuration)
+          disabled = configuration.disabled_rules
+          return false if disabled.include?(RULE_PLUGIN_API_SURFACE) || disabled.include?("all")
+
+          Configuration::SeverityProfile.resolve(
+            rule: RULE_PLUGIN_API_SURFACE, authored_severity: :warning,
+            profile: configuration.severity_profile, overrides: configuration.severity_overrides,
+            bleeding_edge_overrides: configuration.bleeding_edge_severity_overrides
+          ) != :off
+        end
+
+        # The interface the call's receiver carries when the call is outside it, or nil.
+        def outside_interface(call_node, scope)
+          return nil if call_node.receiver.nil? || scope.nil?
+
+          interfaces = receiver_interfaces(scope.type_of(call_node.receiver))
+          return nil if interfaces.nil?
+
+          environment = scope.environment
+          method_name = call_node.name
+          return nil if interfaces.any? { |interface| declares?(environment, interface, method_name) }
+          return nil if object_member?(environment, method_name)
+          return nil unless plugin_source?(scope)
+
+          interfaces.first
+        end
+
+        def diagnostics(path, results)
+          results.map { |result| build(path, result.call_node, result.interface, result.call_node.name) }
+        end
+
+        # The interface facets the receiver carries, or nil when it is anything but `Dynamic[Interface]` arms and
+        # `nil`. A union whose non-nil arms include another type has a member the call may resolve on.
+        def receiver_interfaces(type)
+          case type
+          when Type::Dynamic
+            facet = type.static_facet
+            [facet] if facet.is_a?(Type::Interface)
+          when Type::Union
+            union_interfaces(type)
+          end
+        end
+
+        def union_interfaces(union)
+          interfaces = []
+          union.members.each do |member|
+            next if nil_type?(member)
+            return nil unless member.is_a?(Type::Dynamic) && member.static_facet.is_a?(Type::Interface)
+
+            interfaces << member.static_facet
+          end
+          interfaces.empty? ? nil : interfaces
+        end
+
+        def nil_type?(type)
+          (type.is_a?(Type::Constant) && type.value.nil?) ||
+            (type.is_a?(Type::Nominal) && type.class_name == "NilClass")
+        end
+
+        # An interface that does not resolve declares nothing the rule can read, so it is treated as declaring
+        # every member. A guard: the carrier exists only for an interface the loader translated, so no fixture
+        # reaches it.
+        def declares?(environment, interface, method_name)
+          definition = environment.rbs_loader.interface_definition(interface.name)
+          return true if definition.nil?
+
+          definition.methods.key?(method_name.to_sym)
+        end
+
+        def object_member?(environment, method_name)
+          !Rigor::Reflection.instance_method_definition("Object", method_name, environment: environment).nil?
+        end
+
+        # Whether the call is plugin source: lexically inside a class that inherits `Rigor::Plugin::Base`. A
+        # `Rigor::Plugin::Base` body is not: its chain holds `Base` only as itself. An unrecorded nesting (a scope
+        # built outside a declaration walk) is not either.
+        def plugin_source?(scope)
+          nesting = scope.lexical_nesting
+          return false if nesting.nil? || nesting.empty?
+
+          nesting.any? { |name| inherits_plugin_base?(scope, name) }
+        end
+
+        # Whether `class_name`'s instance chain ({Scope::ResolutionChain}, the one ancestry reader) holds
+        # `Rigor::Plugin::Base` below the class itself. Reading it files the ADR-46 class dependencies, so
+        # an incremental recheck re-judges the call when a declaration on the chain changes in another file. A
+        # truncated chain reads as no plugin: the rule withholds where it cannot see the whole chain.
+        def inherits_plugin_base?(scope, class_name)
+          root = class_name.to_s
+          chain = Scope::ResolutionChain.for(scope, root, :instance, :methods)
+          chain.record(scope)
+          return false if chain.truncated?
+
+          chain.entries.any? { |entry| entry.name != root && plugin_base_entry?(entry) }
+        end
+
+        # `Rigor::Plugin::Base` is external where only its RBS and the gem declare it, and a project entry where the
+        # analysed tree holds its source (Rigor's own `lib`, or a reopen).
+        def plugin_base_entry?(entry)
+          entry.external? ? entry.candidates.include?(PLUGIN_BASE) : entry.name == PLUGIN_BASE
+        end
+
+        def build(path, call_node, interface, method_name)
+          Diagnostic.from_message_loc(
+            call_node,
+            rule: RULE_PLUGIN_API_SURFACE,
+            path: path,
+            message: "`#{method_name}' is not part of the plugin API: `#{interface.describe}' does not declare it. " \
+                     "The engine object answers it today, but Rigor does not promise to keep it; call a member the " \
+                     "interface declares (sig/rigor/plugin/interfaces.rbs) or a public namespace " \
+                     "(docs/internal-spec/public-api.md)",
+            severity: :warning,
+            receiver_type: nil,
+            method_name: method_name
+          )
+        end
+      end
+    end
+  end
+end

data/lib/rigor/analysis/check_rules/published_constant_guard.rb

@@ -115,15 +115,19 @@ module Rigor
         # exemption exactly rather than on the last segment. A path that renders no qualified name falls back
         # to its own last segment, which is all there is to ask about.
         def published_path?(node, scope)
-          rendered = Source::ConstantPath.qualified_name_or_nil(node) || node.name&.to_s
+          rendered = constant_spelling(node)
           !rendered.nil? && scope.published_constant?(rendered)
         end
 
         # The one hop. Resolves the callee through the ordinary `Scope` accessors (so the ADR-46 recorder sees
         # the read and the caller gains an edge to the callee — the conservative direction) and scans its
         # body. Fails soft to false: a resolution this cannot make is not a reason to withhold.
+        #
+        # Issue #3199 — the empty-table shortcut is taken only when no ADR-46 recorder is watching: the scan's
+        # `Scope#published_constant?` questions are what record the `constant:` edges, and a reader that skipped
+        # them would not be re-checked when another file publishes a constant the callee's body names.
         def callee_reads_published_constant?(node, scope)
-          return false if scope.published_constant_names.empty?
+          return false if scope.published_constant_names.empty? && !Analysis::DependencyRecorder.recording?
 
           def_node = resolve_callee(node, scope)
           return false if def_node.nil?
@@ -172,10 +176,30 @@ module Rigor
           end
         end
 
-        # An explicit worklist rather than recursion, so the node budget is one loop-carried local instead of
-        # a shared mutable cell (the engine value-pins a one-element Array counter and then self-flags the
-        # guard's own `negative?` as an always-falsey condition — this rule's own medicine).
         def body_reads_published_constant?(root, scope)
+          scan_body(root) { |node| return true if published_constant_node?(node, scope) }
+          false
+        end
+
+        # Issue #3186 — the constant spellings the one hop's body scan would ask `Scope#published_constant?` about,
+        # sorted and de-duplicated: every node {#body_reads_published_constant?} visits within its budget, in its
+        # order. The hop's answer for any reader is a function of this list and of that reader's publication
+        # tables, so the ADR-89 WD2 gate stores it beside a def's return summary and compares it on an edit: a
+        # reader the gate skips would otherwise keep a withholding (or a firing) the edited body no longer earns.
+        def body_constant_spellings(root)
+          spellings = []
+          scan_body(root) do |node|
+            spelling = constant_spelling(node)
+            spellings << spelling unless spelling.nil?
+          end
+          spellings.uniq.sort
+        end
+
+        # Yields each node of `root` the hop's scan visits, stopping once {BODY_SCAN_BUDGET} is spent. An explicit
+        # worklist rather than recursion, so the node budget is one loop-carried local instead of a shared mutable
+        # cell (the engine value-pins a one-element Array counter and then self-flags the guard's own `negative?`
+        # as an always-falsey condition — this rule's own medicine).
+        def scan_body(root)
           stack = [root]
           budget = BODY_SCAN_BUDGET
           until stack.empty?
@@ -183,19 +207,24 @@ module Rigor
             next unless node.is_a?(Prism::Node)
 
             budget -= 1
-            return false if budget.negative?
-            return true if published_constant_node?(node, scope)
+            return if budget.negative?
 
+            yield node
             node.rigor_each_child { |child| stack << child }
           end
-          false
         end
 
         def published_constant_node?(node, scope)
+          spelling = constant_spelling(node)
+          !spelling.nil? && scope.published_constant?(spelling)
+        end
+
+        # The name a constant reference asks the publication tables about ({#published_path?}'s rendering for a
+        # path), or nil for any other node and for a path that renders no name.
+        def constant_spelling(node)
           case node
-          when Prism::ConstantReadNode then scope.published_constant?(node.name.to_s)
-          when Prism::ConstantPathNode then published_path?(node, scope)
-          else false
+          when Prism::ConstantReadNode then node.name.to_s
+          when Prism::ConstantPathNode then Source::ConstantPath.qualified_name_or_nil(node) || node.name&.to_s
           end
         end
 

data/lib/rigor/analysis/check_rules/rbs_receiver_surface.rb

@@ -36,10 +36,36 @@ module Rigor
         MISSING_HOOK = :method_missing
         # The roots whose project mixins `Inference::ObjectMixins` answers for.
         OBJECT_ROOTS = %w[Object Kernel BasicObject].to_set.freeze
-        private_constant :MISSING_HOOK, :OBJECT_ROOTS
+        # Issue #2792 — the owners of a `method_missing` every object (and every class object) reaches. Core's
+        # `BasicObject#method_missing` raises `NoMethodError`, so it opens nothing; core declares none on the others,
+        # which are here so that a project or gem RBS reopening `Object`, `Kernel`, `Module` or `Class` with one cannot
+        # silence the rule for every receiver.
+        UNIVERSAL_HOOK_OWNERS = {
+          instance: OBJECT_ROOTS,
+          singleton: (OBJECT_ROOTS | %w[Module Class]).freeze
+        }.freeze
+        private_constant :MISSING_HOOK, :OBJECT_ROOTS, :UNIVERSAL_HOOK_OWNERS
 
         module_function
 
+        # Issue #2792 — whether RBS gives `class_name`'s `side` a `method_missing` from somewhere other than the
+        # universal roots: the class itself, an RBS ancestor or an included module (`Delegator` for a
+        # `SimpleDelegator`, `class W < SimpleDelegator`, `OpenStruct`). Ruby sends any name the receiver lacks there,
+        # private or public, so no name is provably missing. Only the absence verdict reads it: the call's type stays
+        # what an unresolved call answers.
+        def rbs_missing_hook?(scope, class_name, side)
+          definition =
+            if side == :singleton
+              Rigor::Reflection.singleton_method_definition(class_name, MISSING_HOOK, scope: scope)
+            else
+              Rigor::Reflection.instance_method_definition(class_name, MISSING_HOOK, scope: scope)
+            end
+          owner = definition&.defined_in
+          return false if owner.nil?
+
+          !UNIVERSAL_HOOK_OWNERS.fetch(side).include?(owner.to_s.delete_prefix("::"))
+        end
+
         # Whether the project may answer `method_name` on an instance of `class_name` through one of its RBS
         # ancestors.
         def ancestor_may_answer?(scope, class_name, method_name)

data/lib/rigor/analysis/check_rules/replaced_singleton_defs.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../../inference/scope_indexer"
+
+module Rigor
+  module Analysis
+    module CheckRules
+      # Issue #3155 — the singleton defs of one file that a later def of the same name certainly replaces, which
+      # `def.return-type-mismatch` does not check against the class's signature: Ruby keeps the later body.
+      #
+      # Both defs must be certain singleton defs of the same class or module body: a direct statement of that body
+      # (`def self.x`, or `def K.x` where `K` names the class), or a direct statement of a `class << self` there
+      # (`def x`, or `def K.x`). A def in a block (`Class.new do … end`, `Struct.new(…) do … end`), under a condition,
+      # loop or `begin`/`rescue`, or in a method body may not run, or runs on another object, so it replaces nothing,
+      # and a def written there is never read as replaced either. A reopening in another file is not read.
+      #
+      # The walk groups defs by the class or module body node only; whether a constant receiver names the class is
+      # read from the def's own Scope (`self_type`, the indexer's declaration context), so it derives none itself.
+      class ReplacedSingletonDefs
+        def initialize(root, scope_index)
+          @root = root
+          @scope_index = scope_index
+        end
+
+        def replaced?(def_node) = offsets.include?(def_node.location.start_offset)
+
+        # `def (self).x` and `def (K).x` name the receiver inside parentheses.
+        def self.unparenthesized(node)
+          while node.is_a?(Prism::ParenthesesNode)
+            body = node.body
+            node = body.is_a?(Prism::StatementsNode) && body.body.size == 1 ? body.body.first : body
+          end
+          node
+        end
+
+        private
+
+        def offsets
+          @offsets ||= collect
+        end
+
+        def collect
+          replaced = Set.new
+          each_class_body(@root) do |body|
+            last = {}
+            certain_singleton_defs(body).each do |def_node|
+              replaced << last[def_node.name].location.start_offset if last.key?(def_node.name)
+              last[def_node.name] = def_node
+            end
+          end
+          replaced
+        end
+
+        def each_class_body(node, &)
+          return if node.nil?
+
+          yield node.body if node.is_a?(Prism::ClassNode) || node.is_a?(Prism::ModuleNode)
+          node.rigor_each_child { |child| each_class_body(child, &) }
+        end
+
+        def certain_singleton_defs(body)
+          statements(body).flat_map do |stmt|
+            case stmt
+            when Prism::DefNode
+              lexical_self?(stmt.receiver, stmt, self_allowed: true) ? [stmt] : []
+            when Prism::SingletonClassNode
+              next [] unless lexical_self?(stmt.expression, stmt, self_allowed: true)
+
+              statements(stmt.body).select do |inner|
+                inner.is_a?(Prism::DefNode) &&
+                  (inner.receiver.nil? || lexical_self?(inner.receiver, inner, self_allowed: false))
+              end
+            else
+              []
+            end
+          end
+        end
+
+        # `at` is the node whose Scope names the class: its `self_type` is the class or its singleton.
+        def lexical_self?(node, at, self_allowed:)
+          node = self.class.unparenthesized(node)
+          return self_allowed if node.is_a?(Prism::SelfNode)
+
+          self_type = @scope_index[at]&.self_type
+          return false unless self_type.respond_to?(:class_name)
+
+          Inference::ScopeIndexer.def_receiver_targets_lexical_self?(node, self_type.class_name.split("::"))
+        end
+
+        def statements(body) = body.is_a?(Prism::StatementsNode) ? body.body : []
+      end
+    end
+  end
+end

data/lib/rigor/analysis/check_rules/rule_ids.rb

@@ -81,6 +81,12 @@ module Rigor
       # Issue #1692 (the ADR-47 WD5 amendment) — a call to the `ruby2_keywords` family Ruby 4.1 deprecates. Runs only
       # under an explicit `target_ruby` of 4.1 or later; see {RubyDeprecations}.
       RULE_DEPRECATED_RUBY2_KEYWORDS = "call.deprecated-ruby2-keywords"
+      # ADR-128 WD6 / ADR-130 slice 2 (#2686) — a call in plugin source on a `Rigor::Plugin` interface value to a
+      # member the interface does not declare. Authored `:warning`, resolved `:off` by every profile and promoted
+      # only by the `plugin-api-surface` bleeding-edge feature. The one built-in id under `plugin.`, the prefix a
+      # plugin's own rows carry as `plugin.<id>.<rule>`: it is in {ALL_RULES}, so `disable:`, markers and
+      # `severity_overrides:` resolve it as a catalogue id before any plugin-id reading.
+      RULE_PLUGIN_API_SURFACE = "plugin.api-surface"
 
       ALL_RULES = [
         RULE_UNDEFINED_METHOD,
@@ -117,7 +123,8 @@ module Rigor
         RULE_EFFECT_LISKOV_WIDENED,
         RULE_EFFECT_UNKNOWN_LABEL,
         RULE_EFFECT_ANNOTATIONS_UNCHECKED,
-        RULE_CONTRADICTING_SIGNATURE
+        RULE_CONTRADICTING_SIGNATURE,
+        RULE_PLUGIN_API_SURFACE
       ].freeze
 
       # Backward-compat alias table (ADR-8 § "Backward compatibility"). Existing user code with

data/lib/rigor/analysis/check_rules/void_value_use_collector.rb

@@ -100,7 +100,7 @@ module Rigor
           return unless value_node.is_a?(Prism::CallNode)
 
           scope = @scope_index[value_node]
-          origin = scope&.void_origins&.[](value_node)
+          origin = scope&.void_origin(value_node)
           return if origin.nil?
 
           @results << Result.new(void_node: value_node, origin: origin)