rigortype 0.1.15 → 0.1.17

data/plugins/rigor-sidekiq/lib/rigor/plugin/sidekiq.rb

@@ -58,14 +58,11 @@ module Rigor
         version: "0.1.0",
         description: "Validates Sidekiq `Worker.perform_async` argument arity.",
         config_schema: {
-          "worker_search_paths" => :array,
-          "worker_marker_modules" => :array
+          "worker_search_paths" => { kind: :array, default: ["app/workers", "app/sidekiq"] },
+          "worker_marker_modules" => { kind: :array, default: %w[Sidekiq::Job Sidekiq::Worker] }
         }
       )
 
-      DEFAULT_WORKER_SEARCH_PATHS = ["app/workers", "app/sidekiq"].freeze
-      DEFAULT_WORKER_MARKER_MODULES = %w[Sidekiq::Job Sidekiq::Worker].freeze
-
       producer :worker_index do |_params|
         WorkerDiscoverer.new(
           io_boundary: io_boundary,
@@ -75,20 +72,30 @@ module Rigor
       end
 
       def init(_services)
-        @worker_search_paths = Array(config.fetch("worker_search_paths", DEFAULT_WORKER_SEARCH_PATHS)).map(&:to_s)
-        @worker_marker_modules = Array(
-          config.fetch("worker_marker_modules", DEFAULT_WORKER_MARKER_MODULES)
-        ).map(&:to_s)
+        @worker_search_paths = Array(config.fetch("worker_search_paths")).map(&:to_s)
+        @worker_marker_modules = Array(config.fetch("worker_marker_modules")).map(&:to_s)
         @worker_index = nil
         @load_error = nil
       end
 
+      # File-level only: the load-error emission. The per-call arity
+      # validation runs over the engine-owned walk via the node_rule
+      # below (ADR-37). The worker index is lazily loaded + memoised by
+      # worker_index_or_nil, shared by both surfaces.
       def diagnostics_for_file(path:, scope:, root:) # rubocop:disable Lint/UnusedMethodArgument
         index = worker_index_or_nil
         return [load_error_diagnostic(path)] if index.nil? && @load_error
-        return [] if index.nil? || index.empty?
 
-        Analyzer.diagnose(path: path, root: root, worker_index: index).map { |diag| build_diagnostic(diag) }
+        []
+      end
+
+      node_rule Prism::CallNode do |node, _scope, path|
+        index = worker_index_or_nil
+        next [] if index.nil? || index.empty?
+
+        Analyzer.violations_for(call_node: node, worker_index: index).map do |violation|
+          diagnostic(node, path: path, message: violation.message, severity: violation.severity, rule: violation.rule)
+        end
       end
 
       private
@@ -96,7 +103,8 @@ module Rigor
       def worker_index_or_nil
         return @worker_index if @worker_index
 
-        @worker_index = cache_for(:worker_index, params: {}).call
+        descriptor = glob_descriptor(@worker_search_paths, "**/*.rb")
+        @worker_index = cache_for(:worker_index, params: {}, descriptor: descriptor).call
       rescue StandardError => e
         @load_error = "rigor-sidekiq: failed to discover workers: #{e.class}: #{e.message}"
         nil
@@ -110,13 +118,6 @@ module Rigor
           rule: "load-error"
         )
       end
-
-      def build_diagnostic(diag)
-        Rigor::Analysis::Diagnostic.new(
-          path: diag.path, line: diag.line, column: diag.column,
-          message: diag.message, severity: diag.severity, rule: diag.rule
-        )
-      end
     end
 
     Rigor::Plugin.register(Sidekiq)

data/plugins/rigor-sorbet/lib/rigor/plugin/sorbet/catalog_walker.rb

@@ -106,6 +106,21 @@ module Rigor
             if pending_sig && def_node?(child)
               record_def_with_sig(child, pending_sig, state, lexical_path, in_singleton_class)
               pending_sig = nil
+            elsif pending_sig && attr_macro_call?(child)
+              # `sig { returns(T) }` above `attr_reader :name` /
+              # `attr_accessor` / `attr_writer` types the generated
+              # accessor(s). This is a first-class Sorbet idiom — not
+              # a dangling sig — so record the accessor signature(s)
+              # instead of warning.
+              record_attr_with_sig(child, pending_sig, state, lexical_path, in_singleton_class)
+              pending_sig = nil
+            elsif pending_sig && (inner_def = visibility_wrapped_def(child))
+              # `sig { ... }` above `private def foo` /
+              # `private_class_method def self.foo` / `module_function
+              # def bar` — a visibility macro wrapping the very def the
+              # sig types. Record the inner def, not a dangling sig.
+              record_def_with_sig(inner_def, pending_sig, state, lexical_path, in_singleton_class)
+              pending_sig = nil
             elsif sig_call?(child)
               state.record_error(:duplicate_sig, pending_sig) if pending_sig
               pending_sig = child
@@ -171,6 +186,64 @@ module Rigor
           node.is_a?(Prism::DefNode)
         end
 
+        VISIBILITY_MACROS = %i[
+          private public protected
+          private_class_method public_class_method module_function
+        ].freeze
+
+        # `private def foo` / `private_class_method def self.bar` /
+        # `module_function def baz` — a receiverless visibility macro
+        # whose single argument is the `def` it wraps. Returns the
+        # inner `Prism::DefNode` (so a preceding sig types it), or nil.
+        # The def's own receiver still drives instance-vs-singleton, so
+        # `private_class_method def self.bar` records as singleton.
+        def visibility_wrapped_def(node)
+          return nil unless node.is_a?(Prism::CallNode) && node.receiver.nil?
+          return nil unless VISIBILITY_MACROS.include?(node.name)
+
+          args = node.arguments&.arguments
+          return nil unless args&.size == 1 && args.first.is_a?(Prism::DefNode)
+
+          args.first
+        end
+
+        ATTR_MACROS = %i[attr_reader attr_writer attr_accessor].freeze
+
+        # `attr_reader :a, :b` / `attr_writer` / `attr_accessor` —
+        # a receiverless attribute macro whose arguments are all
+        # symbol literals (the only shape a preceding `sig` types).
+        def attr_macro_call?(node)
+          return false unless node.is_a?(Prism::CallNode) && node.receiver.nil?
+          return false unless ATTR_MACROS.include?(node.name)
+
+          args = node.arguments&.arguments
+          !args.nil? && !args.empty? && args.all?(Prism::SymbolNode)
+        end
+
+        # Records the method signature(s) a `sig` contributes to the
+        # accessor(s) it precedes: the reader `name` and/or the
+        # writer `name=`, each carrying the sig's `returns(...)`
+        # type. `attr_reader` emits the reader, `attr_writer` the
+        # writer, `attr_accessor` both — for every symbol argument.
+        def record_attr_with_sig(attr_node, sig_call, state, lexical_path, in_singleton_class)
+          parsed = SigParser.parse(sig_call)
+          if parsed.is_a?(SigParser::ParseError)
+            state.record_error(parsed.reason, sig_call)
+            return
+          end
+
+          class_name = lexical_path.empty? ? "Object" : lexical_path.join("::")
+          kind = in_singleton_class ? :singleton : :instance
+          reader = attr_node.name != :attr_writer
+          writer = attr_node.name != :attr_reader
+
+          attr_node.arguments.arguments.each do |arg|
+            name = arg.unescaped
+            catalog_record(state.catalog, class_name, name.to_sym, kind, parsed) if reader
+            catalog_record(state.catalog, class_name, :"#{name}=", kind, parsed) if writer
+          end
+        end
+
         def record_def_with_sig(def_node, sig_call, state, lexical_path, in_singleton_class)
           parsed = SigParser.parse(sig_call)
           if parsed.is_a?(SigParser::ParseError)

data/plugins/rigor-sorbet/lib/rigor/plugin/sorbet/type_translator.rb

@@ -38,6 +38,7 @@ module Rigor
       # | `T.class_of(C)`          | `Singleton[C]`                           |
       # | `[A, B]` (tuple in sig)  | `Tuple[A, B]`                            |
       # | `{a: A, b: B}` (shape)   | `HashShape{a: A, b: B}` (closed)         |
+      # | `Foo::Bar[A, B]` (user)  | `Nominal["Foo::Bar", [A, B]]`            |
       #
       # Anything else (`T.proc`, `T.attached_class`,
       # `T.self_type`, `T.type_parameter`, `T::Struct` / `T::Enum`
@@ -101,16 +102,26 @@ module Rigor
           Rigor::Type::Combinator.nominal_of(name)
         end
 
-        # `Prism::CallNode` covers two distinct surfaces:
+        # `Prism::CallNode` covers three distinct surfaces:
         #
         # 1. `T.something(...)` — `untyped` / `anything` /
         #    `noreturn` / `nilable` / `any` / `all` / `class_of`.
         # 2. `T::SomeClass[...]` — the `[]` method on a generic
         #    `T::*` constant (slice 3 widening). Maps to
         #    `Nominal[name, type_args]`.
+        # 3. `Some::User::Generic[...]` — the `[]` method on any
+        #    OTHER constant (a user-defined generic application,
+        #    e.g. `Mangrove::Result::Ok[String, StandardError]`).
+        #    Maps to `Nominal[name, type_args]` so generic carriers
+        #    authored outside Sorbet's `T::*` set round-trip with
+        #    their instantiation intact (the unwrap-site receiver a
+        #    plugin like rigor-mangrove reads `type_args` from).
+        #    Without this branch such forms degraded to `untyped`,
+        #    silently dropping the receiver's generic arguments.
         def translate_call(node)
           return translate_t_method(node) if sorbet_t_namespaced?(node.receiver)
           return translate_t_subscript(node) if sorbet_subscript?(node)
+          return translate_user_subscript(node) if user_generic_subscript?(node)
 
           degraded
         end
@@ -188,6 +199,37 @@ module Rigor
           end
         end
 
+        # A user-defined generic application — a `[]` call on a
+        # constant that is NOT `T`-rooted, e.g.
+        # `Mangrove::Result::Ok[String, StandardError]` or a
+        # top-level `Box[Integer]`. Translates to
+        # `Nominal[name, type_args]`, recursively translating each
+        # argument (so nested `T::Array[...]` inside a user generic
+        # still resolves). Ordered AFTER `translate_t_subscript` in
+        # `translate_call`, so the `T::*` forms never reach here.
+        def user_generic_subscript?(node)
+          return false unless node.name == :[]
+
+          receiver = node.receiver
+          return false unless receiver.is_a?(Prism::ConstantReadNode) ||
+                              receiver.is_a?(Prism::ConstantPathNode)
+
+          # `T::Foo[...]` is handled by translate_t_subscript; only
+          # non-`T`-rooted constants are user generics.
+          !sorbet_t_qualified?(receiver)
+        end
+
+        def translate_user_subscript(node)
+          # Parity with translate_constant_path: the constant's
+          # rendered name (carrying a leading `::` for absolute
+          # paths) becomes the nominal class name.
+          name = constant_path_name(node.receiver)
+          return degraded if name.nil?
+
+          args = call_arguments(node).map { |arg| translate(arg) }
+          Rigor::Type::Combinator.nominal_of(name, type_args: args)
+        end
+
         # `T::Class[T]` — Sorbet's "any class object whose
         # instances are at least `T`". Rigor has no exact
         # analogue (Singleton names a specific class); the

data/plugins/rigor-sorbet/lib/rigor/plugin/sorbet.rb

@@ -76,29 +76,29 @@ module Rigor
         version: "0.1.0",
         description: "Ingests Sorbet `sig` blocks as method-signature contributions.",
         config_schema: {
+          # `paths` keeps a `fetch`-with-default in `init` because its
+          # default is dynamic (the project's configured `paths`), not a
+          # static literal the manifest can declare.
           "paths" => :array,
-          "rbi_paths" => :array,
-          "enforce_sigil" => :boolean
+          # Default RBI directory tree. Matches the layout `tapioca init`
+          # generates — see Sorbet's `rbi.md`. Slice 4 walks every `.rbi`
+          # file under these roots recursively; the four standard Tapioca
+          # subdirectories (`gems` / `annotations` / `dsl` / `shims`) are
+          # picked up as a side effect of recursing into the parent root.
+          "rbi_paths" => { kind: :array, default: ["sorbet/rbi"] },
+          "enforce_sigil" => { kind: :boolean, default: true }
         }
       )
 
-      # Default RBI directory tree. Matches the layout
-      # `tapioca init` generates — see Sorbet's `rbi.md`. Slice 4
-      # walks every `.rbi` file under these roots recursively;
-      # the four standard Tapioca subdirectories
-      # (`gems` / `annotations` / `dsl` / `shims`) are picked
-      # up as a side effect of recursing into the parent root.
-      DEFAULT_RBI_PATHS = ["sorbet/rbi"].freeze
-
       def init(services)
         @services = services
         @configured_paths = Array(config.fetch("paths", services.configuration.paths)).map(&:to_s)
-        @rbi_paths = Array(config.fetch("rbi_paths", DEFAULT_RBI_PATHS)).map(&:to_s)
-        # Default `true` — only files marked `# typed: true` /
+        @rbi_paths = Array(config.fetch("rbi_paths")).map(&:to_s)
+        # Schema default `true` — only files marked `# typed: true` /
         # `:strict` / `:strong` contribute their sigs. Set to
         # `false` to record every file's sigs regardless of
         # sigil (current behaviour pre-this-config).
-        @enforce_sigil = config.fetch("enforce_sigil", true)
+        @enforce_sigil = config.fetch("enforce_sigil")
         # ADR-11 deferred follow-up — per-call-site assertion
         # gating. Catalog harvest's `@sigil_by_path` cache is
         # consulted at every `flow_contribution_for` call so
@@ -503,11 +503,9 @@ module Rigor
       end
 
       def absurd_diagnostic(path, call_node)
-        location = call_node.location
-        Rigor::Analysis::Diagnostic.new(
+        Rigor::Analysis::Diagnostic.from_node(
+          call_node,
           path: path,
-          line: location.start_line,
-          column: location.start_column + 1,
           message: "`T.absurd` is reachable: the discriminant did not narrow to `T.noreturn`. " \
                    "Either add the missing case branch above the `else`, or remove the " \
                    "`T.absurd(...)` call.",
@@ -558,11 +556,9 @@ module Rigor
       end
 
       def reveal_type_diagnostic(path, call_node, display)
-        location = call_node.location
-        Rigor::Analysis::Diagnostic.new(
+        Rigor::Analysis::Diagnostic.from_node(
+          call_node,
           path: path,
-          line: location.start_line,
-          column: location.start_column + 1,
           message: "`T.reveal_type` inferred type: #{display}",
           severity: :info,
           rule: "reveal-type"
@@ -616,11 +612,9 @@ module Rigor
       end
 
       def assert_type_mismatch_diagnostic(path, call_node, inferred_display, asserted_display)
-        location = call_node.location
-        Rigor::Analysis::Diagnostic.new(
+        Rigor::Analysis::Diagnostic.from_node(
+          call_node,
           path: path,
-          line: location.start_line,
-          column: location.start_column + 1,
           message: "`T.assert_type!` failed: inferred type #{inferred_display} is not " \
                    "compatible with asserted type #{asserted_display}.",
           severity: :error,
@@ -629,11 +623,9 @@ module Rigor
       end
 
       def parse_error_diagnostic(path, error)
-        location = error.node.location
-        Rigor::Analysis::Diagnostic.new(
+        Rigor::Analysis::Diagnostic.from_node(
+          error.node,
           path: path,
-          line: location.start_line,
-          column: location.start_column + 1,
           message: parse_error_message(error.kind),
           severity: :warning,
           rule: "parse-error"

data/plugins/rigor-statesman/lib/rigor/plugin/statesman.rb

@@ -2,6 +2,7 @@
 
 require "prism"
 require "rigor/plugin"
+require "rigor/source/literals"
 
 module Rigor
   module Plugin
@@ -50,41 +51,51 @@ module Rigor
         version: "0.1.0",
         description: "Validates state-machine transition references against declared states.",
         config_schema: {
-          "dsl_method" => :string,
-          "state_method" => :string,
-          "transition_method" => :string
+          "dsl_method" => { kind: :string, default: "state_machine" },
+          "state_method" => { kind: :string, default: "state" },
+          "transition_method" => { kind: :string, default: "transition_to" }
         }
       )
 
-      DEFAULT_DSL_METHOD = "state_machine"
-      DEFAULT_STATE_METHOD = "state"
-      DEFAULT_TRANSITION_METHOD = "transition_to"
-      DID_YOU_MEAN_DISTANCE = 3
-
       def init(_services)
-        @dsl_method = config.fetch("dsl_method", DEFAULT_DSL_METHOD).to_sym
-        @state_method = config.fetch("state_method", DEFAULT_STATE_METHOD).to_sym
-        @transition_method = config.fetch("transition_method", DEFAULT_TRANSITION_METHOD).to_sym
+        @dsl_method = config.fetch("dsl_method").to_sym
+        @state_method = config.fetch("state_method").to_sym
+        @transition_method = config.fetch("transition_method").to_sym
+      end
+
+      # ADR-37 — the two-pass shape made explicit. The collect pass
+      # (pass 1) runs once per file as the node-rule file context: it
+      # MUST complete before validation because a `transition_to` may
+      # precede the `state` that declares its target, so it cannot be a
+      # per-node rule in the engine's single forward walk. The validate
+      # pass (pass 2) is then a per-`CallNode` rule over the
+      # engine-owned walk — no hand-rolled traversal.
+      node_file_context do |root, _scope|
+        collect_states(root)
       end
 
-      def diagnostics_for_file(path:, scope:, root:) # rubocop:disable Lint/UnusedMethodArgument
-        states = collect_states(root)
-        return [] if states.empty?
+      node_rule Prism::CallNode do |node, _scope, path, states|
+        next [] if states.nil? || states.empty?
+        next [] unless transition_call?(node)
 
-        validate_transitions(path, root, states)
+        sym = literal_symbol_arg(node, 0)
+        next [] if sym.nil? # not a literal — defer to runtime
+
+        [build_diagnostic(path, node, sym, states)]
       end
 
       private
 
       # Pass 1 — every `state :foo` declaration inside a
       # `<dsl_method> do ... end` block on the file. Returns a
-      # frozen Set of state name Symbols.
+      # frozen Set of state name Symbols. Walks via the engine's
+      # shared `Source::NodeWalker` rather than a hand-rolled traversal.
       def collect_states(root)
         states = Set.new
-        walk(root) do |node|
+        Source::NodeWalker.each(root) do |node|
           next unless dsl_call?(node)
 
-          walk(node.block) do |inner|
+          Source::NodeWalker.each(node.block) do |inner|
             next unless state_declaration?(inner)
 
             sym = literal_symbol_arg(inner, 0)
@@ -94,33 +105,19 @@ module Rigor
         states.freeze
       end
 
-      # Pass 2 — every `<transition_method>(:sym)` call.
-      def validate_transitions(path, root, states)
-        diagnostics = []
-        walk(root) do |node|
-          next unless transition_call?(node)
-
-          sym = literal_symbol_arg(node, 0)
-          next if sym.nil? # not a literal — defer to runtime
-
-          diagnostics << build_diagnostic(path, node, sym, states)
-        end
-        diagnostics
-      end
-
       def build_diagnostic(path, node, sym, states)
         if states.include?(sym)
           diagnostic(
-            path, node,
-            severity: :info,
-            rule: "known-state",
-            message: "#{@transition_method}(:#{sym}) — declared state"
+            node, path: path,
+                  severity: :info,
+                  rule: "known-state",
+                  message: "#{@transition_method}(:#{sym}) — declared state"
           )
         else
-          hint = did_you_mean(sym, states)
+          hint = Rigor::Plugin::Base.suggest(sym, states)
           message = "unknown state :#{sym}"
           message += " (did you mean :#{hint}?)" if hint
-          diagnostic(path, node, severity: :error, rule: "unknown-state", message: message)
+          diagnostic(node, path: path, severity: :error, rule: "unknown-state", message: message)
         end
       end
 
@@ -143,64 +140,7 @@ module Rigor
       end
 
       def literal_symbol_arg(call, index)
-        node = call.arguments.arguments[index]
-        return nil unless node.is_a?(Prism::SymbolNode)
-
-        node.unescaped.to_sym
-      end
-
-      def walk(node, &)
-        return if node.nil?
-
-        yield node
-        node.compact_child_nodes.each { |child| walk(child, &) }
-      end
-
-      def did_you_mean(name, states)
-        target = name.to_s
-        best = nil
-        best_distance = DID_YOU_MEAN_DISTANCE + 1
-        states.each do |state|
-          distance = levenshtein(target, state.to_s)
-          if distance < best_distance
-            best = state
-            best_distance = distance
-          end
-        end
-        best
-      end
-
-      def levenshtein(a, b) # rubocop:disable Naming/MethodParameterName
-        return b.length if a.empty?
-        return a.length if b.empty?
-
-        rows = Array.new(a.length + 1) { |_i| Array.new(b.length + 1, 0) }
-        (0..a.length).each { |i| rows[i][0] = i }
-        (0..b.length).each { |j| rows[0][j] = j }
-
-        (1..a.length).each do |i|
-          (1..b.length).each do |j|
-            cost = a[i - 1] == b[j - 1] ? 0 : 1
-            rows[i][j] = [
-              rows[i - 1][j] + 1,
-              rows[i][j - 1] + 1,
-              rows[i - 1][j - 1] + cost
-            ].min
-          end
-        end
-        rows[a.length][b.length]
-      end
-
-      def diagnostic(path, node, severity:, rule:, message:)
-        location = node.location
-        Rigor::Analysis::Diagnostic.new(
-          path: path,
-          line: location.start_line,
-          column: location.start_column + 1,
-          message: message,
-          severity: severity,
-          rule: rule
-        )
+        Rigor::Source::Literals.symbol(call.arguments.arguments[index])
       end
     end
 

data/sig/rigor/cache.rbs

@@ -0,0 +1,19 @@
+module Rigor
+  module Cache
+    # Structural interface for the RBS-derived cache producers: a class
+    # object that responds to `.fetch(loader:, store:)` and yields the
+    # cached (or freshly computed) value. A structural *interface*
+    # (duck-typed), not a "protocol" (reserved for ADR-28). Satisfied by
+    # `RbsCacheProducer` and every subclass; matches the _Type and
+    # _DispatchTier interfaces declared elsewhere in sig/.
+    interface _CacheProducer
+      def fetch: (loader: untyped, store: untyped) -> untyped
+    end
+
+    # Base owning the shared producer `fetch` wiring; subclasses add a
+    # PRODUCER_ID constant and a private `self.compute(loader)`.
+    class RbsCacheProducer
+      def self.fetch: (loader: untyped, store: untyped) -> untyped
+    end
+  end
+end

data/sig/rigor/inference.rbs

@@ -57,6 +57,28 @@ module Rigor
     module MethodDispatcher
       def self?.dispatch: (receiver_type: Type::t?, method_name: Symbol, arg_types: Array[Type::t], ?block_type: Type::t?, ?environment: Environment?) -> Type::t?
       def self?.expected_block_param_types: (receiver_type: Type::t?, method_name: Symbol, arg_types: Array[Type::t], ?environment: Environment?) -> Array[Type::t]
+
+      # Immutable value object threaded through every dispatch tier.
+      class CallContext
+        attr_reader receiver: Type::t?
+        attr_reader method_name: Symbol
+        attr_reader args: Array[Type::t]
+        attr_reader block_type: Type::t?
+        attr_reader environment: Environment?
+        attr_reader call_node: untyped
+        attr_reader scope: untyped
+        attr_reader self_type_override: Type::t?
+        attr_reader public_only: bool
+
+        def self.build: (receiver: Type::t?, method_name: Symbol, args: Array[Type::t], ?block_type: Type::t?, ?environment: Environment?, ?call_node: untyped, ?scope: untyped, ?self_type_override: Type::t?, ?public_only: bool) -> CallContext
+        def with: (**untyped) -> CallContext
+      end
+
+      # The interface every dispatch tier observes: fold one call site,
+      # returning a `Type::t` or nil to defer to the next tier.
+      interface _DispatchTier
+        def try_dispatch: (CallContext) -> Type::t?
+      end
     end
 
     class MethodParameterBinder

data/sig/rigor/plugin/access_denied_error.rbs

@@ -1,3 +1,5 @@
-class Rigor::Plugin::AccessDeniedError
+# `< StandardError` so inherited `Exception` methods (`message`,
+# `backtrace`, …) resolve on a rescued instance.
+class Rigor::Plugin::AccessDeniedError < StandardError
   def initialize: (untyped, reason: untyped, ?resource: untyped) -> void
 end

data/sig/rigor/plugin/base.rbs

@@ -1,6 +1,61 @@
+# The plugin contract every Rigor plugin subclasses. The signatures
+# below are the RBS face of `lib/rigor/plugin/base.rb`; they let the
+# `lib` Steep target check Base's own implementation against the
+# declared surface and give plugin subclasses (once they enter a check
+# target) method resolution for the DSL + hook surface.
+#
+# Collaborators that have no RBS yet (Diagnostic, Cache::Descriptor,
+# FlowContribution, NodeContext, Prism nodes) are typed `untyped`; the
+# precision ceiling is the sparse `sig/` tree, not this file.
 class Rigor::Plugin::Base
-  def self.manifest: () -> Rigor::Plugin::Manifest
+  # --- class-level declaration DSLs ---------------------------------
+
+  # Dual-purpose: `manifest(id:, version:, ...)` declares + caches,
+  # the no-arg `manifest` reads the cached value back.
+  def self.manifest: (**untyped fields) -> Rigor::Plugin::Manifest
+
+  def self.producer: (untyped id, ?serialize: untyped, ?deserialize: untyped) { (untyped params) -> untyped } -> Symbol
+  def self.producers: () -> Hash[Symbol, untyped]
+
+  def self.node_rule: (untyped node_type) { (*untyped) -> untyped } -> untyped
+  def self.node_rules: () -> Array[untyped]
+
+  def self.node_file_context: () { (untyped root, untyped scope) -> untyped } -> untyped
+  def self.node_file_context_block: () -> untyped
+
+  def self.dynamic_return: (receivers: Array[String]) { (untyped call_node, untyped scope) -> untyped } -> nil
+  def self.dynamic_returns: () -> Array[untyped]
+
+  def self.type_specifier: (methods: Array[untyped]) { (untyped call_node, untyped scope) -> untyped } -> nil
+  def self.type_specifiers: () -> Array[untyped]
+
+  def self.suggest: (untyped name, untyped candidates) -> String?
+
+  # --- instance surface --------------------------------------------
+
+  attr_reader services: untyped
+  attr_reader config: untyped
+
   def initialize: (services: untyped, ?config: untyped) -> void
-  def init: (untyped) -> nil
-  def prepare: (untyped) -> nil
+
+  # Overridable lifecycle / extension hooks (default no-ops).
+  def init: (untyped services) -> nil
+  def prepare: (untyped services) -> nil
+  def flow_contribution_for: (call_node: untyped, scope: untyped) -> untyped
+  def diagnostics_for_file: (path: untyped, scope: untyped, root: untyped) -> Array[untyped]
+
+  # Engine-executed dispatch over the declared DSLs.
+  def node_rule_diagnostics: (path: untyped, scope: untyped, root: untyped) -> Array[untyped]
+  def dynamic_return_type: (call_node: untyped, scope: untyped, receiver_type: untyped) -> untyped
+  def type_specifier_facts: (call_node: untyped, scope: untyped) -> Array[untyped]
+
+  # Authoring helpers.
+  def diagnostic: (untyped node, path: untyped, message: untyped, ?severity: untyped, ?rule: untyped, ?location: untyped) -> untyped
+  def manifest: () -> Rigor::Plugin::Manifest
+  def signature_paths: () -> Array[String]
+  def protocol_contracts: () -> untyped
+  def io_boundary: () -> Rigor::Plugin::IoBoundary
+  def cache_for: (untyped producer_id, ?params: untyped, ?descriptor: untyped) -> untyped
+  def glob_descriptor: (untyped roots, *untyped patterns) -> untyped
+  def plugin_entry: () -> untyped
 end

data/sig/rigor/plugin/io_boundary.rbs

@@ -1,4 +1,7 @@
 class Rigor::Plugin::IoBoundary
   def initialize: (policy: untyped, plugin_id: untyped, ?http_client: untyped) -> void
   def read_file: (untyped) -> String
+  def open_url: (untyped url) -> String
+  # Returns a frozen `Rigor::Cache::Descriptor` (no RBS yet -> untyped).
+  def cache_descriptor: () -> untyped
 end