rigortype 0.4.6 → 0.4.8

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

@@ -42,8 +42,8 @@ module Rigor
     # `IoBoundary`. The catalog is frozen after the first build and consulted by the `dynamic_return` rule
     # at every gated call site. RBI files share the catalog with project-source sigs — both produce
     # `MethodSignature` entries keyed by `(class_name, method_name, kind)`. When a key collides across
-    # files, the last-walked sig wins (ordering is platform-dependent: `Dir.glob` returns directory
-    # entries in filesystem order). Sorbet's full shim-override semantics — `sorbet/rbi/shims/` overriding
+    # files, the last-walked sig wins (`Dir.glob` results are sorted, so the walk order is stable).
+    # Sorbet's full shim-override semantics — `sorbet/rbi/shims/` overriding
     # `sorbet/rbi/gems/` — lands in a later slice once the catalog gains per-source provenance.
     #
     # The plugin emits `plugin.sorbet.parse-error` warnings for malformed sig blocks (no block / empty
@@ -79,12 +79,10 @@ module Rigor
           "rbi_paths" => { kind: :array, default: ["sorbet/rbi"] },
           "enforce_sigil" => { kind: :boolean, default: true }
         },
-        # #1097 — bundled sorbet-runtime DSL surface (`sig/sorbet.rbs`). `sig` itself reaches the
-        # class object through `extend T::Sig` (or the `< T::ImmutableStruct` / `< T::Enum`
-        # family, which carry the edge themselves), which is
-        # why `rbs_complete_extends:` — the extend-edge allow-list — carries `T::Sig` /
-        # `T::Helpers` / `T::Generic`, and `rbs_complete_ancestors:` carries the Struct/Enum family
-        # for the subclass bridge.
+        # #1097 — bundled sorbet-runtime DSL surface (`sig/sorbet.rbs`). `sig` reaches the class object
+        # through `extend T::Sig` (or the `T::Struct` / `T::Enum` family, which carry the edge themselves):
+        # `rbs_complete_extends:` is that extend-edge allow-list, and `rbs_complete_ancestors:` carries the
+        # Struct/Enum family for the subclass bridge.
         signature_paths: ["sig"],
         rbs_complete_extends: %w[T::Sig T::Helpers T::Generic],
         rbs_complete_ancestors: %w[T::Struct T::InexactStruct T::ImmutableStruct T::Enum],
@@ -122,8 +120,7 @@ module Rigor
         @configured_paths = Array(config.fetch("paths", services.configuration.paths)).map(&:to_s)
         @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).
+        # their sigs. Set to `false` to record every file's sigs regardless of sigil.
         @enforce_sigil = config.fetch("enforce_sigil")
         # Per-call-site assertion gating: `@sigil_by_path` (built during catalog harvest) is consulted so
         # `T.let` / `T.cast` / `T.must` / `T.bind` / `T.assert_type!` only fire in files Sorbet itself
@@ -135,20 +132,20 @@ module Rigor
         @parse_errors_by_path = {}
         @catalog_built = false
         # ADR-11 slice 6 — Prism nodes for `T.absurd` calls we observed in the `dynamic_return` rule to be
-        # *reachable* (i.e., their discriminant didn't narrow to `bot`). `diagnostics_for_file` walks the
-        # per-file AST and surfaces these as `plugin.sorbet.absurd-reachable` warnings. Hash is keyed on
-        # the Prism node's `object_id` because the runner only parses each file once per run, so identity
-        # is stable across the two plugin hooks.
+        # *reachable* (i.e., their discriminant didn't narrow to `bot`). The node rule below surfaces these
+        # as `plugin.sorbet.absurd-reachable` warnings. The Hash is keyed by node identity
+        # (`compare_by_identity`) because the runner only parses each file once per run, so identity is
+        # stable across the two plugin hooks.
         @reachable_absurd_nodes = {}.compare_by_identity
         # ADR-11 light follow-up — `T.reveal_type` calls observed in the `dynamic_return` rule, paired
         # with the display string for the inferred type at the call site. Mirrors the absurd-node
-        # compare-by-identity hash; `diagnostics_for_file` surfaces each entry as a
+        # compare-by-identity hash; the node rule below surfaces each entry as a
         # `plugin.sorbet.reveal-type` `:info` diagnostic.
         @reveal_type_calls = {}.compare_by_identity
         # T.bind / T.assert_type! priority slice 1 — `T.assert_type!` calls observed in the
         # `dynamic_return` rule whose static subtype check FAILED, paired with the inferred + asserted
-        # type display strings. Same compare-by-identity discipline. `diagnostics_for_file` walks the
-        # file AST for `T.assert_type!` calls and surfaces matching entries as
+        # type display strings. Same compare-by-identity discipline. The node rule below surfaces matching
+        # entries as
         # `plugin.sorbet.assert-type-mismatch` `:error` diagnostics.
         @assert_type_mismatches = {}.compare_by_identity
       end
@@ -245,7 +242,7 @@ module Rigor
         # analysis treats code after it as unreachable; the legacy contribution's `exceptional: :raises`
         # slot was never consumed on the dispatcher path — only `return_type` survives the merge). When
         # the discriminant *isn't* narrowed to `bot` at this scope, also records the call node so
-        # `diagnostics_for_file` can surface a `plugin.sorbet.absurd-reachable` warning.
+        # the node rule can surface a `plugin.sorbet.absurd-reachable` warning.
         if AbsurdRecognizer.absurd_call?(call_node)
           @reachable_absurd_nodes[call_node] = true unless AbsurdRecognizer.exhaustive?(call_node, scope)
           return Rigor::Type::Combinator.bot
@@ -255,7 +252,7 @@ module Rigor
         # cheaper to recognise (no catalog walk required) and they win over any cataloged signature: the
         # user explicitly asserted the type at the call site. The light follow-up extends the recogniser
         # to `T.must_because` (alias of `T.must`) and `T.reveal_type` (passes the type through; the
-        # human-facing diagnostic is recorded here for `diagnostics_for_file` to emit).
+        # human-facing diagnostic is recorded here for the node rule to emit).
         #
         # Per-call-site sigil gating: with `enforce_sigil: true` (default), assertions only fire in files
         # Sorbet itself would enforce. Files at `# typed: false` (or sigil-less, which Sorbet treats as
@@ -347,19 +344,96 @@ module Rigor
         when Rigor::Type::Singleton
           chain_lookup(self_type.class_name, method_name, anchor_kind: :singleton, mixin_kind: :extend)
         when Rigor::Type::Nominal
-          chain_lookup(self_type.class_name, method_name, anchor_kind: :instance, mixin_kind: :include)
+          chain_lookup(self_type.class_name, method_name, anchor_kind: :instance, mixin_kind: :include) ||
+            struct_prop_lookup(self_type.class_name, method_name, scope)
         end
       rescue StandardError
         nil
       end
 
+      # Issue #2541 — after the sig catalog (the class and its mixins) declines an instance-side call, a
+      # `prop` / `const` accessor the class or a superclass declares under a `T::Struct`-family root.
+      # The accessor's type is translated here rather than at harvest: a relative constant in it resolves the
+      # way Ruby's lexical lookup would from the declaring class body — under each enclosing namespace,
+      # innermost first, then at the top level — against the classes the walk declared and the RBS
+      # environment. A constant that resolves nowhere reads `Dynamic[top]`, never a guessed class.
+      def struct_prop_lookup(class_name, method_name, scope)
+        signature = @catalog.lookup_struct_prop(class_name: class_name, method_name: method_name)
+        return signature if signature.nil?
+
+        source, nesting = @catalog.struct_prop_type(signature)
+        return signature if source.nil?
+
+        signature.with(return_type: struct_prop_type(source, nesting, signature.class_name, scope))
+      end
+
+      def struct_prop_type(source, nesting, class_name, scope)
+        @struct_prop_types ||= {}
+        @struct_prop_types[[source, nesting, class_name, scope.nil?]] ||= begin
+          node = Prism.parse(source).value.statements&.body&.first
+          resolve = ->(name) { resolve_struct_constant(name, nesting, class_name, scope) }
+          TypeTranslator.translate(node, resolve)
+        end
+      end
+
+      # Ruby's lookup for a relative constant in the class body: the lexical nesting, innermost first; then
+      # the class's ancestors; then the top level. The nesting step answers a class it finds, and declines
+      # (nil, so the constant reads `Dynamic[top]`) when it meets a constant that is not a declared class.
+      # Ancestry is not modelled precisely: a class or constant of that name under any ancestor declines.
+      # The top level answers only when the struct's ancestry is closed — no class on its walked superclass
+      # chain `include`s or `prepend`s anything, whose constants could shadow it — and no other walked
+      # `*::<name>` exists.
+      def resolve_struct_constant(name, nesting, class_name, scope)
+        environment = scope&.environment
+        return name.delete_prefix("::") if name.start_with?("::")
+
+        nesting.size.downto(1) do |depth|
+          candidate = "#{nesting.first(depth).join('::')}::#{name}"
+          return candidate if struct_constant_class?(candidate, environment)
+          return nil if struct_constant_bound?(candidate, scope)
+        end
+        @catalog.constant_ancestry(class_name).each do |ancestor|
+          candidate = "#{ancestor}::#{name}"
+          return nil if struct_constant_class?(candidate, environment) || struct_constant_bound?(candidate, scope)
+        end
+        return nil if struct_constant_elsewhere?(name)
+        return nil if @catalog.mixes_in_ancestry?(class_name)
+
+        struct_constant_class?(name, environment) ? name : nil
+      end
+
+      def struct_constant_class?(name, environment)
+        @catalog.namespace?(name) || !environment&.nominal_for_name(name).nil?
+      end
+
+      # A walked constant write, or any constant the engine types at the rooted path `::<name>` — an RBS
+      # constant declaration included. The probe goes through the plugin-facing `Scope#type_of` on a parsed
+      # constant-path node; a name nothing declares types as `Dynamic[top]` and is not bound.
+      def struct_constant_bound?(name, scope)
+        return true if @catalog.constant?(name)
+        return false if scope.nil?
+
+        node = Prism.parse("::#{name}").value.statements&.body&.first
+        type = scope.type_of(node)
+        !(type.nil? || type.is_a?(Rigor::Type::Dynamic))
+      rescue StandardError
+        true
+      end
+
+      def struct_constant_elsewhere?(name)
+        @struct_constant_names ||= @catalog.declared_constant_names
+        suffix = "::#{name}"
+        @struct_constant_names.any? { |declared| declared.end_with?(suffix) }
+      end
+
       def instance_chain_lookup(receiver_node, method_name, scope)
         return nil if scope.nil?
 
         receiver_type = scope.type_of(receiver_node)
         return nil unless receiver_type.is_a?(Rigor::Type::Nominal)
 
-        chain_lookup(receiver_type.class_name, method_name, anchor_kind: :instance, mixin_kind: :include)
+        chain_lookup(receiver_type.class_name, method_name, anchor_kind: :instance, mixin_kind: :include) ||
+          struct_prop_lookup(receiver_type.class_name, method_name, scope)
       rescue StandardError
         # `scope.type_of` can raise on unrecognised synthetic nodes; degrade to "no contribution" rather
         # than bubbling the failure into the dispatcher.
@@ -502,8 +576,7 @@ module Rigor
             # ADR-88 WD2 — deterministic fold order matters now that the catalog VALUE is digested into the
             # incremental fact-surface fingerprint: a duplicate `(class, method, kind)` sig's last-wins winner
             # must not vary by machine / run. `Dir.glob` sorts its results by default on Ruby 3.0+, so the fold
-            # order is already stable (the slice-1 comment's "filesystem order" caveat predates that default);
-            # this walk relies on it rather than re-sorting.
+            # order is already stable; this walk relies on it rather than re-sorting.
             Dir.glob("**/*#{ext}", base: absolute).each do |relative|
               harvest_file(canonicalize(File.join(absolute, relative)), catalog, sigil_by_path, parse_errors_by_path)
             end
@@ -552,7 +625,7 @@ module Rigor
                         catalog
                       end
 
-        errors = CatalogWalker.walk(root: result.value, catalog: sig_catalog, path: path)
+        errors = CatalogWalker.walk(root: result.value, catalog: sig_catalog, path: path, struct_catalog: catalog)
         # ADR-88 WD2 — store Marshal-clean `{kind:, line:, column:}` tuples, not the `ParseError` (it holds a
         # live Prism node the producer bundle could not serialise). `diagnostics_for_file` rebuilds the
         # diagnostic from the tuple, at the same 1-based line / `start_column + 1` position `from_node` gave.

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

@@ -11,9 +11,8 @@ module Rigor
     #
     #   1. **Collect pass.** Walk the file once to gather every state name declared inside a
     #      `state_machine do ... end` block (`state :draft`, `state :submitted`, ...).
-    #   2. **Validate pass.** Walk the file again, validating each `transition_to(:sym)` and `event :sym`
-    #      reference against the collected state set. Levenshtein distance ≤ 3 drives the did-you-mean
-    #      suggestions.
+    #   2. **Validate pass.** Walk the file again, validating each `transition_to(:sym)` reference against
+    #      the collected state set. `DidYouMean::SpellChecker` drives the did-you-mean suggestions.
     #
     # Useful for `aasm` / `statesman` / hand-rolled DSLs and any framework where declarations and uses
     # live in the same file. The same skeleton lifts to GraphQL types, ActiveModel validations, route

data/plugins/rigor-typelizer/lib/rigor/plugin/typelizer/serializer_collector.rb

@@ -2,15 +2,15 @@
 
 require "prism"
 
-require "rigor/inference/declaration_walk"
+require "rigor/reflection"
 
 require_relative "serializer_index"
 
 module Rigor
   module Plugin
     class Typelizer < Rigor::Plugin::Base
-      # A {Rigor::Inference::DeclarationWalk} collector over one file: the classes it declares, and whether each
-      # one's own body says `include Typelizer::DSL` / `extend Typelizer::DSL`.
+      # A collector over one file, built on {Rigor::Reflection.class_declarations_in}: the classes it declares, and
+      # whether each one's own body says `include Typelizer::DSL` / `extend Typelizer::DSL`.
       #
       # A `module` that includes the DSL is deliberately not recorded: typelizer registers the module's own
       # name and `target_serializers` then calls `.descendants` on it, which a plain Module lacks. A class that
@@ -22,8 +22,6 @@ module Rigor
       # `included do include Typelizer::DSL end` and a `def` that includes it credit nothing to the lexical
       # class. A `class << self` body is a different node and is not entered either.
       class SerializerCollector
-        include Rigor::Inference::DeclarationWalk::Collector
-
         DSL_MODULE = "Typelizer::DSL"
         DSL_CALLS = %i[include extend].freeze
 
@@ -33,17 +31,10 @@ module Rigor
           @dsl = {}
         end
 
-        def on_declaration(node, context, body_context)
-          return Rigor::Inference::DeclarationWalk::DESCEND unless node.is_a?(Prism::ClassNode)
-
-          name = body_context.prefix.join("::")
-          unless name.empty?
-            superclass = superclass_name(node.superclass)
-            @entries[name] = superclass if superclass || !@entries.key?(name)
-            @nestings[name] = context.nesting || []
-            @dsl[name] = true if dsl_in?(node.body) && !body_context.singleton_cref
-          end
-          Rigor::Inference::DeclarationWalk::DESCEND
+        # Walks `root` (a parsed file's `Prism::Node`) and records what it finds; answers the collector itself.
+        def collect(root)
+          Rigor::Reflection.class_declarations_in(root).each { |declaration| record(declaration) }
+          self
         end
 
         # The classes this file declares, as {SerializerIndex::ClassEntry} values.
@@ -58,6 +49,15 @@ module Rigor
 
         private
 
+        def record(declaration)
+          name = declaration.name
+          node = declaration.node
+          superclass = superclass_name(node.superclass)
+          @entries[name] = superclass if superclass || !@entries.key?(name)
+          @nestings[name] = declaration.nesting
+          @dsl[name] = true if dsl_in?(node.body)
+        end
+
         # Whether a statement reachable without entering a def, block, lambda or nested declaration is a
         # receiverless `include` / `extend` of the DSL module.
         def dsl_in?(node)

data/plugins/rigor-typelizer/lib/rigor/plugin/typelizer/serializer_discoverer.rb

@@ -2,16 +2,15 @@
 
 require "prism"
 
-require "rigor/inference/declaration_walk"
-
 require_relative "serializer_collector"
 require_relative "serializer_index"
 
 module Rigor
   module Plugin
     class Typelizer < Rigor::Plugin::Base
-      # Reads every `.rb` file under the configured typelizer dirs and the project's `paths:` through the plugin's `IoBoundary`, runs a
-      # {SerializerCollector} over each and merges the results into one {SerializerIndex}.
+      # Reads every `.rb` file under the configured typelizer dirs and the project's `paths:` through the
+      # plugin's `IoBoundary`, runs a {SerializerCollector} over each and merges the results into one
+      # {SerializerIndex}.
       class SerializerDiscoverer
         def initialize(io_boundary:, dirs:, project_paths: [])
           @io_boundary = io_boundary
@@ -29,10 +28,7 @@ module Rigor
             parsed = Prism.parse(contents)
             next unless parsed.success?
 
-            collector = SerializerCollector.new
-            Rigor::Inference::DeclarationWalk.run(
-              parsed.value, [collector], Rigor::Inference::DeclarationWalk::Context.root(nesting: [])
-            )
+            collector = SerializerCollector.new.collect(parsed.value)
             in_dirs = dir_files.include?(path)
             entries.concat(collector.class_entries.map { |entry| entry.with(in_dirs: in_dirs) })
           end

data/plugins/rigor-typelizer/lib/rigor/plugin/typelizer/serializer_index.rb

@@ -3,16 +3,16 @@
 module Rigor
   module Plugin
     class Typelizer < Rigor::Plugin::Base
-      # The project's classes (every file of the project's `paths:` and the typelizer `dirs`), as the {SerializerCollector} found them. A frozen value
-      # object the `:serializer_index` producer caches.
+      # The project's classes (every file of the project's `paths:` and the typelizer `dirs`), as the
+      # {SerializerCollector} found them. A frozen value object the `:serializer_index` producer caches.
       #
       # {#roots} answers the one question, conservatively — a wrong "no" costs a missing root, a wrong "yes"
       # hides a dead class.
       class SerializerIndex
         # A class the project declares. `superclass` is the constant as written (`nil` when absent) and
         # `nesting` the `Module.nesting` chain (innermost first) its header was written under, which is where
-        # Ruby resolves that constant. `dsl` is true when its body includes or extends `Typelizer::DSL`; `in_dirs` when a file under the
-        # typelizer `dirs` declares it (only such a class is published as a root).
+        # Ruby resolves that constant. `dsl` is true when its body includes or extends `Typelizer::DSL`;
+        # `in_dirs` when a file under the typelizer `dirs` declares it (only such a class is published as a root).
         ClassEntry = Data.define(:name, :superclass, :nesting, :dsl, :in_dirs)
 
         def initialize(classes:)

data/sig/rigor/analysis/baseline.rbs

@@ -66,9 +66,6 @@ module Rigor
 
       # Always an Array of Bucket — `initialize` freezes what it is given and every caller hands it
       # Bucket instances (parse_row rows, from_diagnostics groups, `without`'s reject, or `[]`).
-      # sig-gen gap: #2321 — `initialize` assigns `buckets.freeze`, an expression derived from the
-      # parameter rather than a bare read of it, so the reader is skipped (untyped return) and the element type
-      # is hand-written.
       attr_reader buckets: Array[Bucket]
 
       # `project_root` is `Pathname.new`'d, so a `Pathname` is accepted as well as a `String`

data/sig/rigor/analysis/check_rules/rule_walk.rbs

@@ -0,0 +1,6 @@
+module Rigor::Analysis::CheckRules::RuleWalk
+end
+
+class Rigor::Analysis::CheckRules::RuleWalk::CollectorDriver
+  def initialize: (untyped) -> void
+end

data/sig/rigor/analysis/fact_store.rbs

@@ -2,8 +2,8 @@ module Rigor
   module Analysis
     module CheckRules
       def self?.diagnose: (path: String, root: untyped, scope_index: Hash[untyped, Scope]) -> Array[Diagnostic]
-      def self?.build_node_collectors: (String path, untyped scope_index, ?untyped root) -> Hash[Symbol, untyped]
-      def self?.node_collector_driver: (Hash[Symbol, untyped] collectors) -> untyped
+      def self?.build_node_collectors: (String path, untyped scope_index, ?untyped root, ?plugin_api_surface: bool) -> Hash[Symbol, untyped]
+      def self?.node_collector_driver: (Hash[Symbol, untyped] collectors) -> Rigor::Analysis::CheckRules::RuleWalk::CollectorDriver
       def self?.shadow_verify_converged_collectors: (String path, untyped root, untyped scope_index, Hash[Symbol, untyped]? collectors) -> void
       def self?.filter_suppressed: (Array[Diagnostic] diagnostics, comments: untyped, disabled_rules: Array[String]) -> Array[Diagnostic]
     end

data/sig/rigor/analysis/reachability/scan_cache.rbs

@@ -3,7 +3,7 @@ module Rigor
     module Reachability
       class ScanCache
         def self.open: (untyped, ?target_ruby: untyped) -> Rigor::Analysis::Reachability::ScanCache
-        def self.source_digest: () -> String
+        def self.source_digest: () -> ("unreadable" | String)
         def initialize: (path: untyped, header: untyped) -> void
         def save: () -> nil
       end

data/sig/rigor/cache/descriptor.rbs

@@ -0,0 +1,14 @@
+class Rigor::Cache::Descriptor::PluginEntry
+  def initialize: (id: untyped, version: untyped, ?config_hash: untyped) -> void
+  def to_h: () -> Hash[String, untyped]
+end
+
+class Rigor::Cache::Descriptor
+  def initialize: (?files: untyped, ?gems: untyped, ?plugins: untyped, ?configs: untyped, ?dependencies: untyped, ?globs: untyped) -> void
+  def self.compose: (*untyped) -> Rigor::Cache::Descriptor
+  def cache_key_for: (producer_id: untyped, ?params: untyped) -> String
+  def to_canonical_bytes: () -> String
+  def to_canonical_hash: () -> Hash[String, untyped]
+  def ==: (untyped) -> (false | true)
+  def hash: () -> Integer
+end

data/sig/rigor/cli/diff_command.rbs

@@ -1,4 +1,4 @@
 class Rigor::CLI::DiffCommand
   def initialize: (argv: untyped, out: untyped, err: untyped) -> void
-  def run: () -> (0 | 1 | Integer)
+  def run: () -> (0 | 1 | 64)
 end

data/sig/rigor/cli/explain_command.rbs

@@ -1,4 +1,4 @@
 class Rigor::CLI::ExplainCommand
   def initialize: (argv: untyped, out: untyped, err: untyped) -> void
-  def run: () -> (0 | Integer)
+  def run: () -> (0 | 64)
 end

data/sig/rigor/effects/registry.rbs

@@ -33,7 +33,7 @@ module Rigor
       def self.load_file: (untyped path) -> Registry
 
       attr_reader vocabulary_version: Integer
-      # sig-gen gap: #2321 — `labels:` is declared `Array[untyped]` (input `untyped`, looks deliberate; a declared
+      # sig-gen gap: #2325 — `labels:` is declared `Array[untyped]` (input `untyped`, looks deliberate; a declared
       # type is authoring intent tracked by #2325, and only then does this row generate; coercion-facing:
       # `map(&:to_s)`); every declared label, sorted. Implied ancestors are recognised by {#known?} but not listed
       # here.
@@ -42,7 +42,7 @@ module Rigor
       # Unmarked residue: `@roots` is computed from `@known` in `initialize`, not assigned from a
       # parameter, so no parameter credit applies.
       attr_reader roots: Array[String]
-      # sig-gen gap: #2321 — `descriptions:` is declared `Hash[untyped, untyped]` (input `untyped`, looks deliberate;
+      # sig-gen gap: #2325 — `descriptions:` is declared `Hash[untyped, untyped]` (input `untyped`, looks deliberate;
       # a declared type is authoring intent tracked by #2325, and only then does this row generate; coercion-facing:
       # keys and texts `to_s`'d); one line per root, from the data file's `descriptions:`.
       attr_reader descriptions: Hash[String, String]

data/sig/rigor/environment.rbs

@@ -19,7 +19,9 @@ module Rigor
     def hkt_scan_failure: () -> [String, String, String?, Symbol]?
 
     def self.default: () -> Environment
-    def self.for_project: (?root: String, ?libraries: Array[String], ?signature_paths: Array[String | _ToPath]?, ?cache_store: untyped?, ?plugin_registry: untyped?, ?dependency_source_index: untyped?, ?rbs_extended_reporter: untyped?, ?boundary_cross_reporter: untyped?, ?source_rbs_synthesis_reporter: untyped?, ?bundler_bundle_path: String?, ?bundler_auto_detect: bool, ?synthetic_method_index: untyped?, ?project_patched_methods: untyped?) -> Environment
+    def self.for_project: (?root: String, ?libraries: Array[String], ?signature_paths: Array[String | _ToPath]?, ?cache_store: untyped?, ?plugin_registry: untyped?, ?dependency_source_index: untyped?, ?rbs_extended_reporter: untyped?, ?boundary_cross_reporter: untyped?, ?source_rbs_synthesis_reporter: untyped?, ?bundler_bundle_path: String?, ?bundler_auto_detect: bool, ?synthetic_method_index: untyped?, ?project_patched_methods: untyped?, ?eager: bool) -> Environment
+    # authored: the return is the `signature_paths:` argument's type (authored intent) or the default ["sig"]; sig-gen types the `||` fallback untyped.
+    def self.project_signature_root_candidates: (Array[String | _ToPath]? signature_paths) -> Array[String | _ToPath]
     # authored: the return is the `signature_paths:` argument's type (authored intent) or the default [Pathname]; sig-gen types the `||` fallback untyped.
     def self.project_signature_roots: (Array[String | _ToPath]? signature_paths, ?root: String) -> Array[String | _ToPath]
 
@@ -36,6 +38,7 @@ module Rigor
     def rbs_module?: (String | Symbol name) -> bool
     def singleton_extended_modules: (String | Symbol name) -> Array[String]
     def class_ordering: (String | Symbol lhs, String | Symbol rhs) -> ordering
+    def prepare_for_typing!: () -> Environment
     def reflection: () -> untyped?
     def missing_rbs_gem_owner: (String | Symbol root_constant_name) -> String?
 

data/sig/rigor/inference.rbs

@@ -3,7 +3,8 @@ module Rigor
     type closure_classification = :non_escaping | :escaping | :unknown
 
     class ExpressionTyper
-      def self.harvest_return_memo: () -> Hash[untyped, Array[untyped]]
+      def self.harvest_return_memo: (?Hash[untyped, Hash[untyped, untyped]]? bucket) -> Hash[untyped, Array[untyped]]
+      def self.current_return_memo: () -> Hash[untyped, Hash[untyped, untyped]]?
       def initialize: (scope: Scope, ?tracer: FallbackTracer?) -> void
       def type_of: (untyped node) -> Type::t
       def return_type_for: (untyped def_node, Type::t receiver, Array[Type::t] arg_types) -> Type::t?
@@ -172,6 +173,8 @@ module Rigor
       def self?.collect_class_decls: (untyped node, Array[String] qualified_prefix, Hash[String, Type::t] accumulator) -> void
       def self?.constant_writes_for_file: (untyped root) -> Hash[String, untyped]
       def self?.constant_literal_value: (untyped rvalue) -> Array[untyped]?
+      # authored: the `Set[String]` values are source paths by contract; a Set's element type stays `untyped` in sig-gen (#2177, #2317), so the generator
+      # would never propose it.
       def self?.finalize_constant_writes: (Hash[String, Hash[String, untyped]] writes) -> [Hash[String, Type::Constant], Hash[String, Set[String]]]
       def self?.propagate: (untyped node, Hash[untyped, Scope] table, Scope parent_scope) -> void
 

data/sig/rigor/plugin/additional_initializer.rbs

@@ -4,15 +4,10 @@ module Rigor
     # the read-before-write nil soundness gate does not widen their ivars. See
     # lib/rigor/plugin/additional_initializer.rb for the full contract.
     class AdditionalInitializer
-      # sig-gen gap: #2321 — `attr_reader` rows over ivars `initialize` assigns from expressions derived from its
-      # parameters are skipped (untyped return); the constructor validates `receiver_constraint` is a non-empty String
-      # and normalizes both lists with `map(&:to_sym)`, so the stored types are hand-written.
       attr_reader receiver_constraint: String
 
-      # sig-gen gap: #2321 — as above.
       attr_reader methods: Array[Symbol]
 
-      # sig-gen gap: #2321 — as above.
       attr_reader block_methods: Array[Symbol]
 
       # The validators accept Symbol or non-empty String elements; `initialize` normalizes to

data/sig/rigor/plugin/base.rbs

@@ -4,9 +4,20 @@
 # 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.
+# ADR-128 WD2 — every hook position takes a plugin-facing interface
+# (`sig/rigor/plugin/interfaces.rbs`), a concrete Prism node class, a
+# `Rigor::Type::t` or a core type, instead of `untyped`. A hook's `scope`
+# is non-nil where every engine call site passes one: the per-file hooks
+# receive the seeded `Scope.empty(...)`, `MethodDispatcher#try_plugin_contribution`
+# returns before consulting a plugin when its scope is nil, and
+# `StatementEvaluator#apply_plugin_assertions` has already read its own. The
+# existing `scope.nil?` guards in plugin source stay valid either way.
+#
+# Collaborators that have no RBS yet (FlowContribution) stay `untyped`;
+# the precision ceiling is the sparse `sig/` tree. A parameter row stays
+# lenient even where its type IS declared — `cache_for`'s `?descriptor:` and
+# `IoBoundary#replay` both take a `Cache::Descriptor` and both read `untyped`
+# — by ADR-107 clause 2, not for want of a declaration.
 class Rigor::Plugin::Base
   # --- class-level declaration DSLs ---------------------------------
 
@@ -17,16 +28,32 @@ class Rigor::Plugin::Base
   def self.producer: (untyped id, ?watch: untyped, ?serialize: untyped, ?deserialize: untyped, ?generation_cap: untyped) { (untyped params) -> untyped } -> Symbol
   def self.producers: () -> Hash[Symbol, untyped]
 
-  def self.node_rule: (untyped node_type) { (*untyped) -> untyped } -> Class
+  # One overload per node class the bundled plugins name, so the block's `node` is that class; `Prism::Node` is the
+  # fallback for any other (RBS cannot write `singleton(N)` over a type variable). The block runs `instance_exec`'d
+  # on the plugin: `file_context` is whatever the `node_file_context` block returned (plugin-defined), and a rule
+  # may answer one diagnostic, an array of them, or nil.
+  def self.node_rule: (singleton(::Prism::CallNode) node_type) { (::Prism::CallNode node, Rigor::Plugin::_Scope scope, String path, untyped file_context, Rigor::Plugin::NodeContext context) -> (Rigor::Analysis::Diagnostic | Array[Rigor::Analysis::Diagnostic] | nil) } -> singleton(::Prism::CallNode)
+                    | (singleton(::Prism::ClassNode) node_type) { (::Prism::ClassNode node, Rigor::Plugin::_Scope scope, String path, untyped file_context, Rigor::Plugin::NodeContext context) -> (Rigor::Analysis::Diagnostic | Array[Rigor::Analysis::Diagnostic] | nil) } -> singleton(::Prism::ClassNode)
+                    | (singleton(::Prism::ProgramNode) node_type) { (::Prism::ProgramNode node, Rigor::Plugin::_Scope scope, String path, untyped file_context, Rigor::Plugin::NodeContext context) -> (Rigor::Analysis::Diagnostic | Array[Rigor::Analysis::Diagnostic] | nil) } -> singleton(::Prism::ProgramNode)
+                    | (singleton(::Prism::Node) node_type) { (::Prism::Node node, Rigor::Plugin::_Scope scope, String path, untyped file_context, Rigor::Plugin::NodeContext context) -> (Rigor::Analysis::Diagnostic | Array[Rigor::Analysis::Diagnostic] | nil) } -> singleton(::Prism::Node)
   def self.node_rules: () -> Array[untyped]
 
-  def self.node_file_context: () { (untyped root, untyped scope) -> untyped } -> void
-  def self.node_file_context_block: () -> (^(untyped root, untyped scope) -> untyped)?
+  def self.node_file_context: () { (::Prism::ProgramNode root, Rigor::Plugin::_Scope scope) -> untyped } -> void
+  def self.node_file_context_block: () -> (^(::Prism::ProgramNode root, Rigor::Plugin::_Scope scope) -> untyped)?
 
-  def self.dynamic_return: (?receivers: (Array[String] | ^() -> Array[String])?, ?methods: (Array[untyped] | ^() -> Array[untyped])?, ?file_methods: (^(untyped path) -> Array[untyped])?) { (untyped call_node, untyped scope) -> untyped } -> nil
+  # A rule with a static `methods:` Array only ever runs its block on a `CallNode`: the name gate
+  # (`Registry#build_name_gates`, `Base#dynamic_return_rule_applies?`) matches on the call's name, which
+  # none of the other nodes in the union below has, so the gate declines them (#2681, #2764). Every other
+  # declaration shape is offered the whole union. A callable `methods:` also only ever sees a `CallNode`
+  # at runtime, since the same gate declines the nameless nodes, but RBS cannot tell a callable from an
+  # Array argument by overload alone, so it keeps the union, which is sound.
+  def self.dynamic_return: (?receivers: (Array[String] | ^() -> Array[String])?, methods: Array[untyped], ?file_methods: (^(String path) -> Array[untyped])?) { (::Prism::CallNode call_node, Rigor::Plugin::_Scope scope) -> Rigor::Type::t? } -> nil
+                         | (?receivers: (Array[String] | ^() -> Array[String])?, ?methods: (Array[untyped] | ^() -> Array[untyped])?, ?file_methods: (^(String path) -> Array[untyped])?) { (::Prism::CallNode | ::Prism::CallOperatorWriteNode | ::Prism::CallOrWriteNode | ::Prism::CallAndWriteNode | ::Prism::IndexOperatorWriteNode | ::Prism::IndexOrWriteNode | ::Prism::IndexAndWriteNode | ::Prism::BlockArgumentNode call_node, Rigor::Plugin::_Scope scope) -> Rigor::Type::t? } -> nil
   def self.dynamic_returns: () -> Array[untyped]
 
-  def self.narrowing_facts: (methods: Array[untyped]) { (untyped call_node, untyped scope) -> untyped } -> nil
+  # The block answers the facts that hold after the call returns normally, or nil. The element is a
+  # `Rigor::FlowContribution::Fact`, which has no RBS declaration yet, so it stays `untyped`.
+  def self.narrowing_facts: (methods: Array[untyped]) { (::Prism::CallNode call_node, Rigor::Plugin::_Scope scope) -> Array[untyped]? } -> nil
   # The engine-facing reader for the declared `narrowing_facts` rules. Named
   # `type_specifiers` before ADR-80; that spelling was removed in 0.3.0.
   def self.narrowing_facts_rules: () -> Array[untyped]
@@ -35,15 +62,16 @@ class Rigor::Plugin::Base
 
   # --- instance surface --------------------------------------------
 
-  attr_reader services: untyped
-  attr_reader config: untyped
+  attr_reader services: Rigor::Plugin::_Services
+  # Schema-driven per plugin, so the values stay `untyped` (ADR-128 WD2).
+  attr_reader config: Hash[String, untyped]
 
-  def initialize: (services: untyped, ?config: untyped) -> void
+  def initialize: (services: Rigor::Plugin::_Services, ?config: Hash[String, untyped]) -> void
 
   # Overridable lifecycle / extension hooks (default no-ops).
-  def init: (untyped services) -> nil
-  def prepare: (untyped services) -> nil
-  def diagnostics_for_file: (path: untyped, scope: untyped, root: untyped) -> Array[untyped]
+  def init: (Rigor::Plugin::_Services services) -> nil
+  def prepare: (Rigor::Plugin::_Services services) -> nil
+  def diagnostics_for_file: (path: String, scope: Rigor::Plugin::_Scope, root: ::Prism::ProgramNode) -> Array[Rigor::Analysis::Diagnostic]
   # authored: hook-contract widening — the element type comes from a plugin gem sig-gen never
   # sees, so no engine work would let it answer; the declared `Array[Rigor::Plugin::TemplateUnit]`
   # over a bare-`[]` default body is the author's contract.
@@ -54,12 +82,19 @@ class Rigor::Plugin::Base
   def declared_members: (untyped class_name) -> Array[untyped]
 
   # Engine-executed dispatch over the declared DSLs.
-  def node_rule_diagnostics: (path: untyped, scope: untyped, root: untyped) -> Array[untyped]
+  def node_rule_diagnostics: (path: String, scope: Rigor::Plugin::_Scope, root: ::Prism::ProgramNode) -> Array[untyped]
   # sig-gen gap: #1007 — the true `return result if result` branch (base.rb:594) flows through an
   # `instance_exec`'d, plugin-supplied Proc that sig-gen's inference does not fold into the return
   # join, so it proposes the literal fallback `nil` instead of the honest contract.
-  def dynamic_return_type: (call_node: untyped, scope: untyped, receiver_type: untyped) -> Rigor::Type::t?
-  def narrowing_facts_for: (call_node: untyped, scope: untyped) -> Array[untyped]
+  # `call_node` is a `CallNode` except where the engine dispatches a compound write or a block argument. The
+  # compound writes (`x.attr op= v`, `x.attr ||= v`, `x.attr &&= v`, and the `x[i]` forms) reach a rule through
+  # `ExpressionTyper#attribute_compound_read_type`, `#call_operator_write_type_for` and `#index_read_dispatch`;
+  # the `&:symbol` block arguments through `ExpressionTyper#symbol_block_return_type` and `#apply_hash_block`.
+  # A rule the name gate does not screen out (a `receivers:`-only rule, for one) is offered those nodes, so the
+  # `dynamic_return` block union above is the full set. A rule that reads a `CallNode`-only member (`receiver`,
+  # `name`, `arguments`) must guard with `call_node.is_a?(::Prism::CallNode)` first (#2717).
+  def dynamic_return_type: (call_node: ::Prism::CallNode | ::Prism::CallOperatorWriteNode | ::Prism::CallOrWriteNode | ::Prism::CallAndWriteNode | ::Prism::IndexOperatorWriteNode | ::Prism::IndexOrWriteNode | ::Prism::IndexAndWriteNode | ::Prism::BlockArgumentNode, scope: Rigor::Plugin::_Scope, receiver_type: Rigor::Type::t) -> Rigor::Type::t?
+  def narrowing_facts_for: (call_node: ::Prism::CallNode, scope: Rigor::Plugin::_Scope) -> Array[untyped]
 
   # Authoring helpers.
   def diagnostic: (untyped node, path: untyped, message: untyped, ?severity: untyped, ?rule: untyped, ?location: untyped) -> Rigor::Analysis::Diagnostic
@@ -84,5 +119,5 @@ class Rigor::Plugin::Base
   def effect_ancestry: () -> Array[Rigor::Plugin::EffectAncestry]
   def io_boundary: () -> Rigor::Plugin::IoBoundary
   def cache_for: (untyped producer_id, ?params: untyped, ?descriptor: untyped) -> Proc
-  def plugin_entry: () -> untyped
+  def plugin_entry: () -> Rigor::Cache::Descriptor::PluginEntry
 end

data/sig/rigor/plugin/effect_attribution.rbs

@@ -19,7 +19,7 @@ module Rigor
       # intent tracked by #2325, and only then does this row generate; coercion-facing: `to_s`), and `initialize`
       # stores the private `validate_receiver!` helper's result (#2312).
       attr_reader receiver: String
-      # sig-gen gap: #2321 — `method:` is `untyped` (input `untyped`, looks deliberate; a declared type is authoring
+      # sig-gen gap: #2325 — `method:` is `untyped` (input `untyped`, looks deliberate; a declared type is authoring
       # intent tracked by #2325, and only then does this row generate; coercion-facing: `String | Symbol`), stored as
       # `method.to_sym`.
       attr_reader method: Symbol
@@ -28,7 +28,7 @@ module Rigor
       # intent tracked by #2325, and only then does this row generate; coercion-facing: `Array()` of anything
       # answering `to_s`), stored from the private `normalize_labels` helper (#2312).
       attr_reader labels: Array[String]
-      # sig-gen gap: #2321 — `narrow:` is `untyped` (input `untyped`, looks deliberate; a declared type is authoring
+      # sig-gen gap: #2325 — `narrow:` is `untyped` (input `untyped`, looks deliberate; a declared type is authoring
       # intent tracked by #2325, and only then does this row generate; coercion-facing: `to_s`, nil kept).
       attr_reader narrow: String?
       attr_reader discharge: bool
@@ -41,7 +41,7 @@ module Rigor
       # intent tracked by #2325, and only then does this row generate; coercion-facing: `to_s`), stored from the
       # private `validate_taint!` helper (#2312).
       attr_reader taint: String?
-      # sig-gen gap: #2321 — `callee:` is `untyped` (input `untyped`, looks deliberate; a declared type is authoring
+      # sig-gen gap: #2325 — `callee:` is `untyped` (input `untyped`, looks deliberate; a declared type is authoring
       # intent tracked by #2325, and only then does this row generate; coercion-facing: `to_s`, nil kept).
       attr_reader callee: String?
       # sig-gen gap: #2312 — `callee_fallbacks:` is `untyped` (input `untyped`, looks deliberate; a declared type is