rigortype 0.3.8 → 0.4.0

data/lib/rigor/signature_path_audit.rb

@@ -16,7 +16,24 @@ module Rigor
   # The audit deliberately mirrors the loader's own acceptance test (`path.directory?` + a
   # recursive `**/*.rbs` glob) so a `:ok` verdict means the loader did load from it and a
   # warning means it did not.
+  #
+  # {.bundled_plugin_routes} answers the mirror-image question — an entry that loads too
+  # *little of the plugin*, rather than nothing at all. See its own comment.
   module SignaturePathAudit
+    # The `plugins/` tree of the engine running this code, anchored from THIS file
+    # (`<root>/lib/rigor/signature_path_audit.rb`) so a git checkout and an installed
+    # `rigortype` gem answer identically — the anchor {Plugin::Loader::ENGINE_ROOT} uses, for
+    # the reason it documents.
+    #
+    # Deliberately re-derived rather than read off `Plugin::Loader`: ADR-87 WD4 keeps this
+    # file, which every `rigor check` loads before the cache probe, off the plugin
+    # subsystem's require graph — and that graph is order-dependent (`plugin/registry.rb`
+    # resolves `NodeRuleWalk` at load, which only `rigor/plugin.rb` has required by then), so
+    # requiring the loader from here fails outright. `signature_path_audit_spec` pins the two
+    # anchors equal, and pins this discovery against `Loader.bundled_plugin_sig_path`, so the
+    # duplication cannot drift unnoticed.
+    BUNDLED_PLUGINS_ROOT = File.expand_path("../../plugins", __dir__).freeze
+
     # One configured `signature_paths:` entry's resolution status.
     #
     # `status` is one of:
@@ -60,17 +77,11 @@ module Rigor
     # `nil` — the unset default, where Rigor auto-detects `<root>/sig` — to get an empty
     # result: an absent auto-detected `sig/` is a normal setup, not a misconfiguration, so it
     # is never audited.
-    #
-    # @param signature_paths [Array<String, Pathname>, nil]
-    # @return [Array<Entry>]
     def self.audit(signature_paths)
       Array(signature_paths).map { |path| classify(path.to_s) }
     end
 
     # The subset of {audit} that resolved to nothing — the entries worth warning about.
-    #
-    # @param signature_paths [Array<String, Pathname>, nil]
-    # @return [Array<Entry>]
     def self.warnings(signature_paths)
       audit(signature_paths).select(&:warning?)
     end
@@ -82,5 +93,141 @@ module Rigor
       count = Dir.glob(File.join(path, "**", "*.rbs")).size
       Entry.new(path: path, status: count.zero? ? :empty : :ok, rbs_file_count: count)
     end
+
+    # One configured entry that reaches the `sig/` of a plugin THIS engine bundles, while
+    # `plugins:` never names that plugin (issue #697).
+    BundledPluginRoute = Data.define(:path, :gem) do
+      # Names the plugin and the one edit that fixes it. The consequence is spelled out
+      # because the symptom the user actually sees is `call.undefined-method` on code that
+      # runs — nothing in that row points back at the `signature_paths:` line.
+      def message
+        "signature_paths: #{path.inspect} loads the signatures of the bundled plugin #{gem.inspect}, " \
+          "which `plugins:` does not name — so the plugin's manifest never loads, and the classes it " \
+          "declares only partially on purpose (ADR-26 `open_receivers:`) are read as complete, which " \
+          "reports methods your code really defines as undefined. " \
+          "Add #{gem.inspect} to `plugins:` instead of naming its `sig/` in `signature_paths:`."
+      end
+
+      def to_h
+        { "path" => path, "gem" => gem, "message" => message }
+      end
+    end
+
+    # The mirror image of {.warnings}: an entry the loader reads perfectly well, which
+    # nevertheless leaves the user worse off than not configuring it.
+    #
+    # A bundled plugin ships two halves that only work together — the RBS under its `sig/`,
+    # and the manifest that says which of those declarations are deliberately partial
+    # (ADR-26 `open_receivers:`). `plugins:` loads both; `signature_paths:` loads only the
+    # first, and the partial declarations then read as complete, so a scope the application
+    # really defines draws `call.undefined-method`. This is a configuration mistake with no
+    # visible cause, so it is reported here rather than fixed by teaching the check rules yet
+    # another route to the same protection — which is [#660](https://github.com/rigortype/rigor/issues/660)'s
+    # question to settle, not this warning's.
+    #
+    # **What it asks is what the entry LOADS, not what it looks like**, exactly as
+    # `Environment::RbsLoader.bundled_overlay_twin_signatures_loaded?` does for the overlay
+    # stand-down: both sides are `File.realpath`'d and matched against the plugin's actual
+    # `.rbs` files, so a symlink or a case-variant spelling answers the same as the directory
+    # itself, and an entry naming a file (or a directory that does not exist) — which the
+    # loader reads nothing from — matches nothing. The two are not single-homed because the
+    # overlay-side predicate lives on the RBS loader, and ADR-87 WD4 keeps this file, which
+    # every `rigor check` loads before the cache probe, off the engine's require graph.
+    #
+    # @param signature_paths — {Configuration#signature_paths}; `nil` (the unset default,
+    #   where Rigor auto-detects `<root>/sig`) is never audited.
+    # @param plugins — the raw {Configuration#plugins} list.
+    def self.bundled_plugin_routes(signature_paths, plugins = [])
+      entries = resolved_entries(signature_paths)
+      return [] if entries.empty?
+
+      root = canonical_path(BUNDLED_PLUGINS_ROOT)
+      return [] if root.nil? || entries.none? { |(_, dir)| overlapping?(dir, root) }
+
+      listed = listed_plugin_names(plugins)
+      bundled_plugin_sig_dirs.reject { |gem, _| listed?(gem, listed) }.flat_map do |gem, sig_dir|
+        files = canonical_rbs_files(sig_dir)
+        next [] if files.empty?
+
+        entries.filter_map do |(entry, dir)|
+          BundledPluginRoute.new(path: entry, gem: gem) if files.any? { |file| under?(file, dir) }
+        end
+      end
+    end
+
+    # `[entry as configured, canonical directory]` for every entry the loader would read from.
+    def self.resolved_entries(signature_paths)
+      Array(signature_paths).filter_map do |entry|
+        dir = canonical_path(entry.to_s)
+        [entry.to_s, dir] if dir && File.directory?(dir)
+      end
+    end
+    private_class_method :resolved_entries
+
+    # Gem name of every plugin the engine bundles that ships signatures, to its `sig/`.
+    # Derived from the `plugins/` tree rather than listed, for {Plugin::FirstParty}'s reason:
+    # a list would be a second source of truth, and its first drift would silently stop
+    # warning about the plugin that drifted.
+    def self.bundled_plugin_sig_dirs
+      return {} unless File.directory?(BUNDLED_PLUGINS_ROOT)
+
+      Dir.children(BUNDLED_PLUGINS_ROOT).sort.filter_map do |gem|
+        sig = File.join(BUNDLED_PLUGINS_ROOT, gem, "sig")
+        [gem, sig] if File.directory?(sig)
+      end.to_h
+    end
+
+    # Every name a `plugins:` entry puts on the record, in both the bare-string and the
+    # `gem:` / `id:` hash forms. An `enabled: false` entry counts as named even though it
+    # loads nothing: the user has demonstrably found the plugin, and telling them to add what
+    # is already there would be worse than staying quiet. Under-warning is this module's
+    # standing FP-safe direction.
+    def self.listed_plugin_names(plugins)
+      Array(plugins).flat_map do |raw|
+        case raw
+        when String then [raw]
+        when Hash
+          keyed = raw.to_h { |key, value| [key.to_s, value] }
+          [keyed["gem"], keyed["id"]].compact.map(&:to_s)
+        else []
+        end
+      end.to_set
+    end
+    private_class_method :listed_plugin_names
+
+    # A bundled plugin's manifest id is its gem name minus the `rigor-` prefix, and `plugins:`
+    # accepts either spelling as `id:`, so both count as naming it.
+    def self.listed?(gem, listed)
+      require_relative "plugin/first_party"
+      listed.include?(gem) || listed.include?(gem.delete_prefix(Plugin::FirstParty::GEM_PREFIX))
+    end
+    private_class_method :listed?
+
+    def self.canonical_rbs_files(dir)
+      Dir.glob(File.join(dir, "**", "*.rbs")).filter_map { |file| canonical_path(file) }
+    end
+    private_class_method :canonical_rbs_files
+
+    # `File.realpath`, not `File.expand_path`: it resolves symlinks and, on a case-folding
+    # filesystem, the on-disk spelling. It raises for a path that does not exist, which is
+    # the answer wanted here — a path the loader cannot read is not a route to anything.
+    def self.canonical_path(path)
+      File.realpath(path.to_s)
+    rescue SystemCallError
+      nil
+    end
+    private_class_method :canonical_path
+
+    def self.under?(path, dir)
+      path.start_with?("#{dir}#{File::SEPARATOR}")
+    end
+    private_class_method :under?
+
+    # Whether the two directories could possibly share a file. The cheap prune that keeps the
+    # per-plugin globs off every run whose `signature_paths:` point at the project's own tree.
+    def self.overlapping?(one, other)
+      one == other || under?(one, other) || under?(other, one)
+    end
+    private_class_method :overlapping?
   end
 end

data/lib/rigor/source/literals.rb

@@ -31,9 +31,6 @@ module Rigor
 
       # The Symbol a literal `Prism::SymbolNode` / `Prism::StringNode` names, or `nil` for any other node
       # (including `nil`).
-      #
-      # @param node [Prism::Node, nil]
-      # @return [Symbol, nil]
       def symbol_or_string(node)
         return nil unless node.is_a?(Prism::SymbolNode) || node.is_a?(Prism::StringNode)
 
@@ -44,9 +41,6 @@ module Rigor
       # (including `nil`). The String-returning sibling of {.symbol_or_string} — for callers that key on the
       # raw name rather than the interned Symbol (route helpers, factory names, filter targets).
       # `#unescaped` round-trips an interpolation-free `:foo` / `"foo"` to `"foo"` for both kinds.
-      #
-      # @param node [Prism::Node, nil]
-      # @return [String, nil]
       def symbol_or_string_name(node)
         return nil unless node.is_a?(Prism::SymbolNode) || node.is_a?(Prism::StringNode)
 
@@ -56,9 +50,6 @@ module Rigor
       # The Symbol a literal `Prism::SymbolNode` names, or `nil` for any other node (including a
       # `Prism::StringNode` and `nil`). Stricter than {.symbol_or_string}: a DSL that accepts only `:draft`
       # and not `"draft"` keeps that distinction by reaching for this rather than the Symbol-or-String form.
-      #
-      # @param node [Prism::Node, nil]
-      # @return [Symbol, nil]
       def symbol(node)
         return nil unless node.is_a?(Prism::SymbolNode)
 
@@ -68,9 +59,6 @@ module Rigor
       # The String a literal `Prism::SymbolNode` names, or `nil` for any other node (including a
       # `Prism::StringNode` and `nil`). The String-returning sibling of {.symbol} — SymbolNode-only, but the
       # caller wants the raw name rather than the interned Symbol.
-      #
-      # @param node [Prism::Node, nil]
-      # @return [String, nil]
       def symbol_name(node)
         return nil unless node.is_a?(Prism::SymbolNode)
 
@@ -79,9 +67,6 @@ module Rigor
 
       # Every literal Symbol/String positional argument of a call, in source order. Non-literal arguments
       # are dropped. Returns `[]` when the call has no argument list.
-      #
-      # @param call_node [Prism::CallNode, nil]
-      # @return [Array<Symbol>]
       def symbol_arguments(call_node)
         args = call_node&.arguments&.arguments
         return [] if args.nil?
@@ -93,20 +78,12 @@ module Rigor
       # {.symbol_name} — for callers that need a predicate rather than an extraction (hash-key matching in
       # keyword or assoc argument positions, e.g. `el.is_a?(AssocNode) && symbol_named?(el.key, "required")`).
       # Uses `#unescaped` (not `#value`) for round-trip consistency.
-      #
-      # @param node [Prism::Node, nil]
-      # @param name [String]
-      # @return [Boolean]
       def symbol_named?(node, name)
         node.is_a?(Prism::SymbolNode) && node.unescaped == name
       end
 
       # The literal Symbol/String at positional `index`, or `nil` when the call has no argument list, the
       # index is out of range, or the argument there is not a literal Symbol/String.
-      #
-      # @param call_node [Prism::CallNode, nil]
-      # @param index [Integer]
-      # @return [Symbol, nil]
       def symbol_arg(call_node, index)
         args = call_node&.arguments&.arguments
         return nil if args.nil?

data/lib/rigor/source/node_children.rb

@@ -106,8 +106,6 @@ module Rigor
       # e.g. `node.body`). Pure and re-entrant; `break` / `next` / `return` in the block behave exactly as they
       # would with `compact_child_nodes.each`. Walkers holding a known `Prism::Node` call `#rigor_each_child`
       # directly; this wrapper is the nil-tolerant entry.
-      #
-      # @yieldparam child [Prism::Node]
       def each_child(node, &)
         node.rigor_each_child(&) if node.is_a?(Prism::Node)
       end

data/lib/rigor/source/node_locator.rb

@@ -22,25 +22,19 @@ module Rigor
       class OutOfRangeError < StandardError; end
 
       class << self
-        # @param source [String]
-        # @param root [Prism::Node]
-        # @param line [Integer] 1-indexed line number
-        # @param column [Integer] 1-indexed column number (byte index within the line)
-        # @return [Prism::Node, nil]
+        # @param line — 1-indexed line number
+        # @param column — 1-indexed column number (byte index within the line)
         def at_position(source:, root:, line:, column:)
           new(source: source, root: root).at_position(line: line, column: column)
         end
 
-        # @param root [Prism::Node]
-        # @param offset [Integer] 0-indexed byte offset
-        # @return [Prism::Node, nil]
+        # @param offset — 0-indexed byte offset
         def at_offset(root:, offset:)
           new(source: nil, root: root).at_offset(offset)
         end
       end
 
-      # @param source [String, nil] used by `#at_position`; may be omitted when only `#at_offset` is needed.
-      # @param root [Prism::Node]
+      # @param source — used by `#at_position`; may be omitted when only `#at_offset` is needed.
       def initialize(source:, root:)
         @source = source
         @root = root
@@ -48,7 +42,7 @@ module Rigor
 
       # Resolve a `(line, column)` pair (1-indexed) to the deepest enclosing node.
       #
-      # @raise [OutOfRangeError] if the line or column falls outside the source buffer.
+      # @raise OutOfRangeError — if the line or column falls outside the source buffer.
       def at_position(line:, column:)
         offset = position_to_offset(line, column)
         at_offset(offset)

data/lib/rigor/source/node_walker.rb

@@ -25,8 +25,6 @@ module Rigor
     module NodeWalker
       module_function
 
-      # @yieldparam node [Prism::Node]
-      # @return [Enumerator] when no block is given.
       def each(root, &)
         return to_enum(__method__, root) unless block_given?
 
@@ -47,10 +45,6 @@ module Rigor
       # itself). The yielded `ancestors` array is the live descent stack — callers that retain it past the
       # block invocation MUST copy it (`Plugin::NodeContext` does). Used by the plugin engine to give
       # `node_rule` blocks their enclosing class / method / block context (ADR-37 slice 1d).
-      #
-      # @yieldparam node [Prism::Node]
-      # @yieldparam ancestors [Array<Prism::Node>]
-      # @return [Enumerator] when no block is given.
       def each_with_ancestors(root, &)
         return to_enum(__method__, root) unless block_given?
 

data/lib/rigor/source/parameter_envelope.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module Source
+    # Issue #992 — the positional-argument envelope of a `Prism::DefNode`, and the ONE place a `def` nobody
+    # declared is turned into something `call.wrong-arity` can check a call against.
+    #
+    # Both undeclared lanes read it. A method known only to the discovery walk has no other shape, and a
+    # method `rigor-rbs-inline` synthesized a fully defaulted skeleton for (`%a{rigor:v1:inferred-signature}`)
+    # is sent here too rather than having its synthesized member's arity read, so a `def` can never be
+    # judged by two parsers of its parameter list that disagree.
+    #
+    # An envelope is plain frozen data, `[min, max, required_keywords]`, because it rides the ADR-85 seed
+    # bundle through `Marshal`: `max` is nil when a rest or `...` parameter leaves it unbounded, and
+    # `required_keywords` is true when the def takes a required keyword — a call that passes positionals
+    # only then fails on the missing keyword whatever its count, which is a different diagnostic than the
+    # one this envelope backs, so the rule declines on it the way `compute_arity_envelope` declines an RBS
+    # function with required keywords.
+    #
+    # {OPAQUE} is the value every other contribution to a name records — `define_method`, `attr_*`, an alias,
+    # a macro that names the method, a second `def` whose envelope differs — and it absorbs under {.merge}.
+    # That makes the per-name fold a join: order-independent, idempotent, and unable to keep one of several
+    # shapes silently.
+    module ParameterEnvelope
+      module_function
+
+      OPAQUE = :opaque
+
+      # The envelope of `def_node`'s own parameter list. Block, keyword-optional and keyword-rest parameters
+      # never change how many positionals the method accepts; `super`, `yield` and `&block` in the body do
+      # not either, so the body is not read at all.
+      def of(def_node)
+        params = def_node.parameters
+        return [0, 0, false].freeze if params.nil?
+
+        required = params.requireds.size + params.posts.size
+        [required, maximum(params, required), required_keywords?(params)].freeze
+      end
+
+      def maximum(params, required)
+        return nil if params.rest || params.keyword_rest.is_a?(Prism::ForwardingParameterNode)
+
+        required + params.optionals.size
+      end
+
+      def required_keywords?(params)
+        params.keywords.any?(Prism::RequiredKeywordParameterNode)
+      end
+
+      # The join of two contributions to one name: equal envelopes stay, anything else is {OPAQUE}.
+      def merge(left, right)
+        return right if left.nil?
+        return left if right.nil?
+
+        left == right ? left : OPAQUE
+      end
+
+      def opaque?(envelope) = envelope == OPAQUE
+
+      # Folds `overlay`'s per-class entries into `base` with {.merge}, returning a new table. Both are
+      # `{class name => {key => envelope}}`.
+      def merge_tables(base, overlay)
+        return overlay if base.nil? || base.empty?
+        return base if overlay.nil? || overlay.empty?
+
+        base.merge(overlay) { |_class, left, right| left.merge(right) { |_key, a, b| merge(a, b) } }
+      end
+    end
+  end
+end

data/lib/rigor/source.rb

@@ -15,3 +15,4 @@ require_relative "source/node_locator"
 require_relative "source/node_walker"
 require_relative "source/literals"
 require_relative "source/constant_path"
+require_relative "source/parameter_envelope"

data/lib/rigor/triage/catalogue.rb

@@ -91,9 +91,7 @@ module Rigor
       INFO_GUARDED = %i[h5_systemic_cluster h6_genuine_bugs].freeze
       private_constant :INFO_GUARDED
 
-      # @param diagnostics [Array<Analysis::Diagnostic>]
-      # @param include_info [Boolean] let H5/H6 see `:info` diagnostics
-      # @return [Array<Hint>]
+      # @param include_info — let H5/H6 see `:info` diagnostics
       def recognise(diagnostics, include_info: false)
         claimed = {}.compare_by_identity
         recognisers.filter_map do |recogniser|

data/lib/rigor/triage.rb

@@ -34,11 +34,9 @@ module Rigor
     # `rbs.coverage.missing-gem`) survives; the count-based H5/H6 recognisers guard against info themselves so
     # recognition trace never reads as a bug.
     #
-    # @param diagnostics [Array<Analysis::Diagnostic>]
-    # @param top [Integer] hotspot-file cap
-    # @param hints [Boolean] run the heuristic catalogue
-    # @param include_info [Boolean] route info into the volume views
-    # @return [Report]
+    # @param top — hotspot-file cap
+    # @param hints — run the heuristic catalogue
+    # @param include_info — route info into the volume views
     def analyze(diagnostics, top: 10, hints: true, include_info: false)
       routed = include_info ? diagnostics : diagnostics.reject { |d| d.severity == :info }
       Report.new(

data/lib/rigor/type/accepts_result.rb

@@ -26,9 +26,8 @@ module Rigor
 
       attr_reader :trinary, :mode, :reasons
 
-      # @param trinary [Rigor::Trinary]
-      # @param mode [Symbol] currently `:gradual` (default) or `:strict`.
-      # @param reasons [Array<String>, String, nil] textual reasons; a
+      # @param mode — currently `:gradual` (default) or `:strict`.
+      # @param reasons — textual reasons; a
       #   single string is wrapped, `nil` becomes an empty array.
       def initialize(trinary, mode: :gradual, reasons: nil)
         raise ArgumentError, "trinary must be Rigor::Trinary, got #{trinary.class}" unless trinary.is_a?(Trinary)
@@ -42,18 +41,37 @@ module Rigor
 
       class << self
         def yes(mode: :gradual, reasons: nil)
-          new(Trinary.yes, mode: mode, reasons: reasons)
+          literal_result(Trinary.yes, mode, reasons)
         end
 
         def no(mode: :gradual, reasons: nil)
-          new(Trinary.no, mode: mode, reasons: reasons)
+          literal_result(Trinary.no, mode, reasons)
         end
 
         def maybe(mode: :gradual, reasons: nil)
-          new(Trinary.maybe, mode: mode, reasons: reasons)
+          literal_result(Trinary.maybe, mode, reasons)
+        end
+
+        private
+
+        # #775 — a result is an immutable value, so one instance serves every site that asks for the same
+        # verdict with the same literal reason (`"structural equality"`, `"exact name match"`, ...): the
+        # acceptance rules answer ~360k times on the lib self-check, most of them through a handful of
+        # such literals, and each answer cost the result plus its reasons array. A reason built at the
+        # site (an unfrozen interpolated String) or a reason list still builds a fresh result.
+        def literal_result(trinary, mode, reasons)
+          literal = reasons.nil? || (reasons.is_a?(String) && reasons.frozen?)
+          return new(trinary, mode: mode, reasons: reasons) unless literal
+
+          by_mode = (@literal_results[trinary] ||= {})
+          by_reason = (by_mode[mode] ||= {})
+          by_reason[reasons] ||= new(trinary, mode: mode, reasons: reasons)
         end
       end
 
+      # `Trinary` verdict => mode => literal reason (or nil) => the shared result.
+      @literal_results = {}
+
       def yes?
         trinary.yes?
       end