rigortype 0.2.8 → 0.3.0

data/plugins/rigor-rbs-inline/lib/rigor/plugin/rbs_inline.rb

@@ -8,9 +8,10 @@ require "rigor/plugin"
 # name: T`, `# @rbs return: T`, attribute `#:`, …) and contributes the result to the analysis environment
 # through the `source_rbs_synthesizer:` manifest hook.
 #
-# By default (WD2) only files starting with the upstream `# rbs_inline: enabled` magic comment are
-# processed; a host context can flip this off by setting `require_magic_comment: false` in the plugin
-# config (WD10).
+# Since ADR-93 WD1 the default is `require_magic_comment: false`: a file is processed whenever it actually
+# carries an annotation (see {Synthesizer#annotated?}), with only the upstream `# rbs_inline: disabled`
+# directive opting a file out. Set `require_magic_comment: true` to restore the old ADR-32 WD2 gate that
+# processed only files opening with `# rbs_inline: enabled`.
 module Rigor
   module Plugin
     # The plugin gem requires `rbs/inline` at load time; without the upstream library the synthesizer can't
@@ -35,9 +36,24 @@ module Rigor
       # env-build time. Returns the synthesised RBS source as a String, or `nil` when the file contributes
       # nothing (no magic comment in the default mode, empty annotation set, parse error per WD6).
       class Synthesizer
-        # @param require_magic_comment [Boolean] when `true` (the default, WD2), only files with
-        #   `# rbs_inline: enabled` at the top are processed. When `false` (WD10 host-context override),
-        #   every file is treated as if it carried the magic comment.
+        # An RDoc directive comment: `#:` followed by a bare word (RDoc allows a hyphen, as in `:call-seq:`)
+        # and a closing colon. RDoc predates rbs-inline by about two decades and `#:<name>:` is
+        # indistinguishable from an rbs-inline `#: <type>` assertion to upstream's parser, which reads the
+        # directive name as a type alias — `def f #:nodoc:` becomes `def f: () -> nodoc`, a type nothing
+        # declares (upstream issue: https://github.com/soutaro/rbs-inline/issues/248).
+        #
+        # Matching on shape rather than a name list covers all 17 directives the Ruby docs list
+        # (https://docs.ruby-lang.org/ja/latest/library/rdoc.html) with nothing to maintain, and none of
+        # `#: () -> void`, `#: String`, `#:Integer`, `#: bool`, `#:my_alias`, `#: { name: String }`,
+        # `#: (name: String) -> void`, `#: Integer?`, `#[Integer]` or `# @rbs x: String` matches it: a valid
+        # RBS type never starts with a bare lowercase word that is immediately closed by a colon. Only the
+        # space-free spelling is affected; `# :nodoc:` never reaches upstream's annotation grammar.
+        RDOC_DIRECTIVE_COMMENT = /\A#:[a-z_][\w-]*:/
+
+        # @param require_magic_comment [Boolean] when `false` (the default since ADR-93 WD1), the magic
+        #   comment is not required and the file is processed only if it actually carries an annotation — see
+        #   {#annotated?}. When `true` (the old ADR-32 WD2 gate), only files opening with
+        #   `# rbs_inline: enabled` are processed, and upstream's opt-in semantics apply verbatim.
         def initialize(require_magic_comment:)
           @require_magic_comment = require_magic_comment
           freeze
@@ -55,6 +71,9 @@ module Rigor
           return nil if source.empty?
 
           result = ::Prism.parse(source)
+          _, result = neutralize_rdoc_directives(source, result)
+          return nil if !@require_magic_comment && !annotated?(result)
+
           # `opt_in: true` is rbs-inline's "require the magic comment" mode (per upstream parser.rb:62).
           # The plugin's `require_magic_comment:` config knob maps directly onto it.
           parsed = ::RBS::Inline::Parser.parse(result, opt_in: @require_magic_comment)
@@ -71,6 +90,56 @@ module Rigor
           # message, without crashing analysis.
           [:error, "#{e.class}: #{e.message.to_s.lines.first.to_s.strip}"]
         end
+
+        private
+
+        # True when the file carries at least one rbs-inline annotation. Gates the magic-comment-free mode,
+        # and is the difference between "honour annotations wherever they are" and "fabricate signatures for
+        # code nobody annotated" — upstream's opt-out mode does the latter, emitting a full
+        # `def f: (untyped x) -> untyped` skeleton for EVERY unannotated def. Rigor trusts an accepted
+        # signature over body inference, so those skeletons would replace real inferred types with `untyped`:
+        # measured on mail (zero annotations) as 26 → 42 diagnostics, i.e. the mode actively fought the
+        # analysis on exactly the projects that write no annotations. The spec binds Rigor to treat
+        # annotations as type sources "whenever present" (`overview.md` § "Compatibility hierarchy"); it does
+        # not ask for untyped shadows of unannotated code.
+        #
+        # Detection delegates to upstream's own `AnnotationParser` rather than scanning for `#:` / `@rbs`
+        # with a regexp: the annotation grammar is upstream's to define (ADR-32 WD3), and this keeps a doc
+        # comment that merely mentions `@rbs`, or a URL containing `#:`, from opting a file in. A file with
+        # the magic comment keeps upstream's semantics verbatim — the author opted that file in explicitly,
+        # skeletons and all, which is what `rbs-inline --output` would generate for it.
+        def annotated?(prism_result)
+          ::RBS::Inline::AnnotationParser.parse(prism_result.comments)
+                                         .any? { |parsed| parsed.each_annotation.any? }
+        end
+
+        # Rewrite every RDoc directive comment to its spaced spelling (`#:nodoc:` -> `# :nodoc:`) so
+        # upstream's annotation grammar never sees it, and re-parse. Two reasons this happens here rather
+        # than in {#annotated?}: the directive must not gate a file in, AND it must not reach the synthesis,
+        # because one mis-parsed directive takes the whole class down with it. `def f #:nodoc:` renders as
+        # `def f: (untyped x) -> nodoc`; `nodoc` resolves to nothing, `RBS::DefinitionBuilder` raises
+        # `NoTypeFoundError` for the class, and every real annotation in that class is silently lost —
+        # measured on a class whose `#: (String) -> Integer` method fell back to body inference because a
+        # sibling method carried `#:nodoc:`. `fileutils.rb` alone carries 29 of these.
+        #
+        # The rewrite touches comment text only, so it cannot change what Ruby does; it shifts columns
+        # within the comment, which nothing downstream reads (the synthesized RBS is fresh text with its own
+        # buffer). Prism decides what is a comment, so a `#:nodoc:` inside a string literal stays put. Files
+        # without a directive re-parse nothing.
+        def neutralize_rdoc_directives(source, prism_result)
+          offsets = prism_result.comments.filter_map do |comment|
+            location = comment.location
+            # `start_character_offset`, not `start_offset`: the latter counts BYTES while `String#insert`
+            # indexes CHARACTERS, so on a file with any multi-byte content the space lands mid-word and
+            # rewrites `#:nodoc:` to `#:n odoc:` — still a directive to upstream, and now a corrupted one.
+            location.start_character_offset if RDOC_DIRECTIVE_COMMENT.match?(location.slice)
+          end
+          return [source, prism_result] if offsets.empty?
+
+          # Back to front, so each insertion leaves the earlier offsets valid.
+          rewritten = offsets.sort.reverse.inject(source.dup) { |acc, offset| acc.insert(offset + 1, " ") }
+          [rewritten, ::Prism.parse(rewritten)]
+        end
       end
 
       manifest(
@@ -87,11 +156,16 @@ module Rigor
       # override (returned by `#manifest`, which `Plugin::Registry#source_rbs_synthesizers` consults via
       # `plugin.manifest.source_rbs_synthesizer`).
       #
-      # ADR-32 WD10 — `require_magic_comment` defaults to `true`. Setting it to `false` in `.rigor.yml`
-      # flips the synthesizer into "process every file" mode.
+      # ADR-93 WD1 — `require_magic_comment` defaults to `false`: annotations are official type sources
+      # "always parsed whenever present" per the binding spec (overview.md § Compatibility hierarchy), so
+      # a file is processed when it actually carries an annotation, with the magic comment not required.
+      # The magic-comment-free mode is annotation-presence-gated (see {Synthesizer#annotated?}), so an
+      # unannotated file contributes nothing and the flip cannot regress it. Set `require_magic_comment:
+      # true` in `.rigor.yml` to restore the ADR-32 opt-in behaviour; `# rbs_inline: disabled` remains the
+      # per-file opt-out either way (honoured by upstream unconditionally).
       def initialize(services:, config: {})
         super
-        @require_magic_comment = config.fetch("require_magic_comment", true) ? true : false
+        @require_magic_comment = config.fetch("require_magic_comment", false) ? true : false
         @synthesizer = Synthesizer.new(require_magic_comment: @require_magic_comment)
         # Build the per-instance manifest eagerly (before `freeze`) so the registry's repeated reads
         # return the same object and we don't need to mutate a frozen instance later.

data/plugins/rigor-rbs-inline/lib/rigor-rbs-inline.rb

@@ -3,16 +3,20 @@
 # rigor-rbs-inline — ingests rbs-inline-shaped comments (`# @rbs name: T`, `#: () -> T`, `# @rbs return: T`,
 # attribute `#:`, ivars, generics, override, …) as RBS contributions to the analysis environment.
 #
-# Per ADR-32 the plugin gates per file on the upstream `# rbs_inline: enabled` magic comment by default. A
-# host context that owns the entire analysis scope (e.g. the ADR-29 browser playground) can set
-# `require_magic_comment: false` in the plugin config to skip the gate — every file the synthesizer sees is
-# treated as if it carried the magic comment.
+# Since ADR-93 WD1 the plugin defaults to `require_magic_comment: false`: annotations are official type
+# sources wherever present, gated only on a file actually carrying one, with `# rbs_inline: disabled` the
+# per-file opt-out. ADR-93 WD2 default-wires this plugin from `Configuration.load` when the upstream
+# `rbs-inline` library is resolvable, so most projects need no `plugins:` entry at all. Restore the old
+# ADR-32 magic-comment gate, or opt out of the auto-wire, through config:
 #
 #     # .rigor.yml
 #     plugins:
 #       - id: rigor-rbs-inline
 #         config:
-#           require_magic_comment: false   # default true
+#           require_magic_comment: true    # default false — restore the ADR-32 magic-comment gate
+#       # or disable the auto-wired default entirely:
+#       # - gem: rigor-rbs-inline
+#       #   enabled: false
 #
 # The plugin depends on the upstream `rbs-inline` gem; Rigor's core `rigortype` gemspec stays zero-dep per
 # ADR-0 / ADR-32 WD1.

data/plugins/rigor-rspec/lib/rigor/plugin/rspec/let_scope_index.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 require "rigor/source/literals"
 
@@ -89,7 +91,7 @@ module Rigor
             return
           end
 
-          node.compact_child_nodes.each do |child|
+          node.rigor_each_child do |child|
             collect(child, anchor: anchor, accumulator: accumulator)
           end
         end

data/plugins/rigor-rspec/lib/rigor/plugin/rspec/scope_walker.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 require "rigor/source/literals"
 
@@ -70,7 +72,7 @@ module Rigor
           if rspec_describe_call?(node)
             scopes << build_scope(node, kind: :rspec_describe)
           else
-            node.compact_child_nodes.each { |child| walk_top_level(child, scopes) }
+            node.rigor_each_child { |child| walk_top_level(child, scopes) }
           end
         end
 

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

@@ -97,6 +97,17 @@ module Rigor
         let_binding_return_type(call_node, scope)
       end
 
+      # ADR-88 WD1 — both contributions are per-file: the matcher narrowing facts come from the call's own AST,
+      # and the `let`-binding return types come from each spec file's OWN `describe`/`let` structure (`let` is
+      # file-scoped). A spec file's edit changes its own content (re-analysed already). The one cross-file input
+      # — the optional factorybot `:factory_index` fact this plugin consumes — is itself an ADR-9 publication
+      # captured in the incremental fact-surface digest via factorybot's own channel, so it need not appear
+      # here. A stable sentinel declares "no OWN cross-file fact surface", keeping the plugin
+      # incremental-capable; `--verify-incremental` backstops the claim.
+      def incremental_state_fingerprint
+        "per-file-lets"
+      end
+
       private
 
       # The `file_methods:` gate set — every `let` / `subject` name the file declares anywhere. A safe

data/plugins/rigor-rspec-rails/lib/rigor/plugin/rspec_rails/http_status_codes.rb

@@ -43,7 +43,10 @@ module Rigor
 
           require "rack/utils"
           @rack_status_symbols = Rack::Utils::SYMBOL_TO_STATUS_CODE.keys.to_set.freeze
-        rescue LoadError, StandardError
+        rescue ::LoadError, ::StandardError
+          # `::`-qualified: in this lexical scope a bare `LoadError` resolves to `Rigor::Plugin::LoadError`
+          # (the plugin-loading error, a StandardError), so the real `::LoadError` (a ScriptError) from a
+          # failed require would escape instead of declining.
           @rack_status_symbols = nil
         end
       end

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 
 require_relative "worker_index"
@@ -67,7 +69,7 @@ module Rigor
           when Prism::ClassNode then visit_class(node, lexical_path, &)
           when Prism::ModuleNode then visit_module(node, lexical_path, &)
           else
-            node.compact_child_nodes.each { |child| walk_for_workers(child, lexical_path, &) }
+            node.rigor_each_child { |child| walk_for_workers(child, lexical_path, &) }
           end
         end
 
@@ -133,7 +135,7 @@ module Rigor
         def lookup_perform_def(body)
           return nil if body.nil?
 
-          body.compact_child_nodes.each do |node|
+          body.rigor_each_child do |node|
             next unless node.is_a?(Prism::DefNode) && node.name == :perform
             next if node.receiver.is_a?(Prism::SelfNode)
 

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 
 require_relative "method_signature"
@@ -58,7 +60,7 @@ module Rigor
             # A `def` not preceded by a `sig` is fine; we just don't record anything for it. The
             # interesting case is in `walk_statements`, which pairs sig+def.
           else
-            node.compact_child_nodes.each do |child|
+            node.rigor_each_child do |child|
               walk_node(child, state, lexical_path: lexical_path, in_singleton_class: in_singleton_class)
             end
           end

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

@@ -116,6 +116,18 @@ module Rigor
         errors.map { |error| parse_error_diagnostic(path, error) }
       end
 
+      # ADR-88 WD2 — the per-run catalog is an ADR-60 record-and-validate producer. Before this it was rebuilt
+      # unconditionally on every `--incremental` recheck (parse + walk every `.rb` / `.rbi` sig tree); as a
+      # producer it is cached to disk keyed on the plugin config, with `watch:` covering the scanned trees so an
+      # added / removed / edited sig file recomputes it. The producer VALUE (a Marshal-clean bundle of the
+      # catalog + the sigil map + the parse-error tuples) is what ADR-88 WD1 digests into the incremental
+      # fact-surface fingerprint, so a sig edit OUTSIDE `signature_paths:` invalidates the snapshot for free.
+      # The bundle is returned (not written to ivars) because a cache HIT does not run the block — the sigil map
+      # and parse errors would otherwise be lost on the warm path.
+      producer :catalog, watch: -> { catalog_watch_globs } do |_params|
+        build_catalog_bundle
+      end
+
       # ADR-52 slice 4 — per-call return-type path via the method-name-gated `dynamic_return` DSL. The
       # recognised name set is only known at run time (the catalog's `def` names come from the lazy
       # catalog build), so it is declared as a callable: the engine `instance_exec`s it once per run on
@@ -389,35 +401,69 @@ module Rigor
         end
       end
 
+      # ADR-88 WD2 — resolve the catalog from the `:catalog` producer (disk-cached) and unpack its Marshal-clean
+      # bundle into the ivars the return-type / sigil-gate / parse-error paths read. `producer_value` memoises
+      # per instance and rescues a producer failure to nil, hence the empty-bundle fallback.
       def ensure_catalog
         return @catalog if @catalog_built
 
+        bundle = producer_value(:catalog) || EMPTY_CATALOG_BUNDLE
+        @catalog = bundle[:catalog]
+        @sigil_by_path = bundle[:sigil_by_path]
+        @parse_errors_by_path = bundle[:parse_errors_by_path]
+        @catalog_built = true
+        @catalog
+      end
+
+      # ADR-88 WD2 — the `watch:` coverage for the `:catalog` producer: the `.rb` sig trees + the `.rbi` trees.
+      # An added / removed file under either invalidates the cached bundle even though the block globbed the
+      # tree itself. Evaluated at `cache_for` time (after `#init`), so `@configured_paths` / `@rbi_paths` are set.
+      def catalog_watch_globs
+        [[@configured_paths, "**/*.rb"], [@rbi_paths, "**/*.rbi"]]
+      end
+
+      # ADR-88 WD2 — build the Marshal-clean catalog bundle the `:catalog` producer caches. Harvests the `.rb`
+      # sig trees then the `.rbi` trees (last-wins ordering preserved from the ivar-mutating original) and
+      # returns `{ catalog:, sigil_by_path:, parse_errors_by_path: }`.
+      def build_catalog_bundle
         catalog = Catalog.new
+        sigil_by_path = {}
+        parse_errors_by_path = {}
         # Project source — `.rb` only.
-        @configured_paths.each { |root| harvest_path(root, catalog, extensions: %w[.rb]) }
+        @configured_paths.each { |root| harvest_path(root, catalog, sigil_by_path, parse_errors_by_path, %w[.rb]) }
         # Sorbet RBI tree — `.rbi` only. Slice 4 of ADR-11.
-        @rbi_paths.each { |root| harvest_path(root, catalog, extensions: %w[.rbi]) }
+        @rbi_paths.each { |root| harvest_path(root, catalog, sigil_by_path, parse_errors_by_path, %w[.rbi]) }
         catalog.freeze!
-        @catalog = catalog
-        @catalog_built = true
-        catalog
+        { catalog: catalog, sigil_by_path: sigil_by_path, parse_errors_by_path: parse_errors_by_path }
       end
 
+      # Frozen empty bundle used when the `:catalog` producer failed (e.g. a project I/O error) so downstream
+      # reads see a well-formed shape rather than nil.
+      EMPTY_CATALOG_BUNDLE = { catalog: Catalog.new.freeze!, sigil_by_path: {}, parse_errors_by_path: {} }.freeze
+      private_constant :EMPTY_CATALOG_BUNDLE
+
       # @param root [String] directory or single file.
       # @param catalog [Catalog]
+      # @param sigil_by_path [Hash{String=>Symbol}] accumulator: harvested file → detected sigil level.
+      # @param parse_errors_by_path [Hash{String=>Array<Hash>}] accumulator: file → `{kind:,line:,column:}` tuples.
       # @param extensions [Array<String>] file extensions to accept (e.g. `[".rb"]` for project source,
       #   `[".rbi"]` for Sorbet RBI tree).
-      def harvest_path(root, catalog, extensions:)
+      def harvest_path(root, catalog, sigil_by_path, parse_errors_by_path, extensions)
         absolute = canonicalize(root)
         if File.directory?(absolute)
           extensions.each do |ext|
+            # 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.
             Dir.glob(File.join(absolute, "**", "*#{ext}")).each do |path|
-              harvest_file(canonicalize(path), catalog)
+              harvest_file(canonicalize(path), catalog, sigil_by_path, parse_errors_by_path)
             end
           end
         elsif File.file?(absolute) && extensions.any? { |ext| absolute.end_with?(ext) }
           # `paths:` may list individual files (the demos do this); walk them directly rather than skipping.
-          harvest_file(absolute, catalog)
+          harvest_file(absolute, catalog, sigil_by_path, parse_errors_by_path)
         end
       end
 
@@ -432,7 +478,7 @@ module Rigor
         expanded
       end
 
-      def harvest_file(path, catalog)
+      def harvest_file(path, catalog, sigil_by_path, parse_errors_by_path)
         contents = io_boundary.read_file(path)
         return if contents.nil?
 
@@ -441,7 +487,7 @@ module Rigor
         # Per-call-site assertion gating consults this map at recognition time. Recorded BEFORE the
         # ignored short-circuit so a `# typed: ignore` file still reports its level to the gate (the gate
         # then chooses to suppress assertions there too — `ignore` is stricter than `false`).
-        @sigil_by_path[path] = level
+        sigil_by_path[path] = level
         return if SigilDetector.ignored?(level)
 
         result = Prism.parse(contents)
@@ -460,13 +506,23 @@ module Rigor
                       end
 
         errors = CatalogWalker.walk(root: result.value, catalog: sig_catalog, path: path)
-        @parse_errors_by_path[path] = errors unless errors.empty?
+        # 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.
+        parse_errors_by_path[path] = errors.map { |error| parse_error_tuple(error) } unless errors.empty?
       rescue Plugin::AccessDeniedError, Errno::ENOENT
         # Skip files outside the trusted read scope or that vanished between glob and read; the plugin
         # produces no output for them.
         nil
       end
 
+      # ADR-88 WD2 — the Marshal-clean position tuple for a `CatalogWalker::ParseError`, capturing the node's
+      # location at harvest time so the producer bundle carries no live Prism node.
+      def parse_error_tuple(error)
+        location = error.node.location
+        { kind: error.kind, line: location.start_line, column: location.start_column + 1 }
+      end
+
       # Emits a `plugin.sorbet.absurd-reachable` warning for the `T.absurd(x)` call recorded in
       # `@reachable_absurd_nodes` during inference; the node rule above does the identity match and pop.
       def absurd_diagnostic(path, call_node)
@@ -535,11 +591,15 @@ module Rigor
         )
       end
 
+      # ADR-88 WD2 — `error` is a Marshal-clean `{kind:, line:, column:}` tuple (the pre-computed node
+      # location), not a Prism-node-bearing `ParseError`; build the diagnostic directly at that position (the
+      # `line` / `column` `from_node` would have derived).
       def parse_error_diagnostic(path, error)
-        Rigor::Analysis::Diagnostic.from_node(
-          error.node,
+        Rigor::Analysis::Diagnostic.new(
           path: path,
-          message: parse_error_message(error.kind),
+          line: error[:line],
+          column: error[:column],
+          message: parse_error_message(error[:kind]),
           severity: :warning,
           rule: "parse-error"
         )

data/sig/prism_node_children.rbs

@@ -0,0 +1,9 @@
+# Declares the reopening `Rigor::Source::NodeChildren` performs at load: a compiled `#rigor_each_child` is defined on
+# every concrete `Prism::*Node` class (allocation-free equivalent of `compact_child_nodes.each`). Declared on the
+# abstract base so every subclass resolves; the runtime definition is per-concrete-class, generated from
+# `Prism::Reflection` in lib/rigor/source/node_children.rb.
+module Prism
+  class Node
+    def rigor_each_child: () { (Prism::Node) -> void } -> void
+  end
+end

data/sig/rigor/environment.rbs

@@ -29,6 +29,7 @@ module Rigor
     def rbs_module?: (String | Symbol name) -> bool
     def class_ordering: (String | Symbol lhs, String | Symbol rhs) -> ordering
     def reflection: () -> untyped?
+    def missing_rbs_gem_owner: (String | Symbol root_constant_name) -> String?
 
     class ClassRegistry
       def self.default: () -> ClassRegistry

data/sig/rigor/inference.rbs

@@ -3,8 +3,10 @@ module Rigor
     type closure_classification = :non_escaping | :escaping | :unknown
 
     class ExpressionTyper
+      def self.harvest_return_memo: () -> Hash[untyped, Array[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?
       def scope: () -> Scope
       def tracer: () -> FallbackTracer?
       def dynamic_top: () -> Type::Dynamic
@@ -27,6 +29,7 @@ module Rigor
 
       def initialize: (scope: Scope, ?tracer: FallbackTracer?, ?on_enter: (^(untyped, Scope) -> void)?, ?class_context: Array[ClassFrame]) -> void
       def evaluate: (untyped node) -> [Type::t, Scope]
+      def content_mutated_parameter_positions: (untyped def_node) -> Array[Integer]
       def scope: () -> Scope
       def tracer: () -> FallbackTracer?
       def sub_eval: (untyped node, Scope with_scope, ?class_context: Array[ClassFrame]) -> [Type::t, Scope]
@@ -163,6 +166,10 @@ module Rigor
       def self?.record_declarations: (untyped node, Array[String] qualified_prefix, Hash[untyped, Type::t] identity_table, Hash[String, Type::t] discovered) -> void
       def self?.discovered_classes_for_paths: (Array[String] paths, ?buffer: untyped) -> Hash[String, Type::t]
       def self?.discovered_def_index_for_paths: (Array[String] paths, ?buffer: untyped) -> Hash[Symbol, untyped]
+      def self?.scan_summary_for_paths: (Array[String] paths, ?buffer: untyped) -> Hash[Symbol, untyped]
+      def self?.code_fingerprint: (String source, untyped comments) -> String
+      def self?.discovered_project_index_for_paths: (Array[String] paths, ?buffer: untyped) -> Hash[Symbol, untyped]
+      def self?.discovered_project_index_incremental: (Array[String] paths, seed_bundles: Hash[String, untyped], ?buffer: untyped) -> Hash[Symbol, untyped]
       def self?.collect_class_decls: (untyped node, Array[String] qualified_prefix, Hash[String, Type::t] accumulator) -> void
       def self?.qualified_name_for: (untyped constant_path_node) -> String?
       def self?.render_constant_path: (untyped node) -> String

data/sig/rigor/plugin/base.rbs

@@ -28,8 +28,7 @@ class Rigor::Plugin::Base
 
   def self.narrowing_facts: (methods: Array[untyped]) { (untyped call_node, untyped scope) -> untyped } -> nil
   # Deprecating alias for `narrowing_facts` (ADR-80); removed in 0.3.0.
-  def self.type_specifier: (methods: Array[untyped]) { (untyped call_node, untyped scope) -> untyped } -> nil
-  def self.type_specifiers: () -> Array[untyped]
+  def self.narrowing_facts_rules: () -> Array[untyped]
 
   def self.suggest: (untyped name, untyped candidates) -> String?
 
@@ -48,7 +47,7 @@ class Rigor::Plugin::Base
   # 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]
+  def narrowing_facts_for: (call_node: untyped, scope: untyped) -> Array[untyped]
 
   # Authoring helpers.
   def diagnostic: (untyped node, path: untyped, message: untyped, ?severity: untyped, ?rule: untyped, ?location: untyped) -> untyped

data/sig/rigor/reflection.rbs

@@ -6,6 +6,7 @@ module Rigor
     def self?.nominal_for_name: (String | Symbol class_name, ?scope: Scope) -> Type::Nominal?
     def self?.singleton_for_name: (String | Symbol class_name, ?scope: Scope) -> Type::Singleton?
     def self?.constant_type_for: (String | Symbol constant_name, ?scope: Scope) -> Type::t?
+    def self?.resolve_constant_type: (String | Symbol name, ?scope: Scope) -> Type::t?
     def self?.instance_method_definition: (String | Symbol class_name, String | Symbol method_name, ?scope: Scope) -> untyped
     def self?.singleton_method_definition: (String | Symbol class_name, String | Symbol method_name, ?scope: Scope) -> untyped
     def self?.instance_definition: (String | Symbol class_name, ?scope: Scope) -> untyped

data/sig/rigor/scope.rbs

@@ -11,6 +11,7 @@ module Rigor
     attr_reader dynamic_origins: Hash[untyped, Symbol]
     attr_reader local_origins: Hash[Symbol, Symbol]
     attr_reader ivar_origins: Hash[Symbol, Symbol]
+    attr_reader void_origins: Hash[untyped, Inference::VoidOrigin]
     attr_reader indexed_narrowings: Hash[IndexedKey, Type::t]
     attr_reader method_chain_narrowings: Hash[ChainKey, Type::t]
     attr_reader source_path: String?
@@ -28,6 +29,7 @@ module Rigor
     def discovered_def_nodes: () -> Hash[String, Hash[Symbol, untyped]]
     def discovered_singleton_def_nodes: () -> Hash[String, Hash[Symbol, untyped]]
     def discovered_def_sources: () -> Hash[String, Hash[Symbol, String]]
+    def discovered_singleton_def_sources: () -> Hash[String, Hash[Symbol, String]]
     def discovered_method_visibilities: () -> Hash[String, Hash[Symbol, Symbol]]
     def discovered_superclasses: () -> Hash[String, String]
     def discovered_includes: () -> Hash[String, Array[String]]
@@ -35,8 +37,11 @@ module Rigor
     def data_member_layouts: () -> Hash[String, Array[Symbol]]
     def struct_member_layouts: () -> Hash[String, { members: Array[Symbol], keyword_init: bool }]
     def param_inferred_types: () -> Hash[[String, Symbol, Symbol], Hash[Symbol, Type::t]]
+    def run_generation: () -> Object?
     def record_dynamic_origin: (untyped node, Symbol cause) -> Scope
 
+    def record_void_origin: (untyped node, Inference::VoidOrigin origin) -> Scope
+
     class DiscoveryIndex
       attr_reader declared_types: Hash[untyped, Type::t]
       attr_reader class_ivars: Hash[String, Hash[Symbol, Type::t]]
@@ -48,6 +53,7 @@ module Rigor
       attr_reader discovered_def_nodes: Hash[String, Hash[Symbol, untyped]]
       attr_reader discovered_singleton_def_nodes: Hash[String, Hash[Symbol, untyped]]
       attr_reader discovered_def_sources: Hash[String, Hash[Symbol, String]]
+      attr_reader discovered_singleton_def_sources: Hash[String, Hash[Symbol, String]]
       attr_reader discovered_method_visibilities: Hash[String, Hash[Symbol, Symbol]]
       attr_reader discovered_superclasses: Hash[String, String]
       attr_reader discovered_includes: Hash[String, Array[String]]
@@ -55,10 +61,11 @@ module Rigor
       attr_reader data_member_layouts: Hash[String, Array[Symbol]]
       attr_reader struct_member_layouts: Hash[String, { members: Array[Symbol], keyword_init: bool }]
       attr_reader param_inferred_types: Hash[[String, Symbol, Symbol], Hash[Symbol, Type::t]]
+      attr_reader run_generation: Object?
 
       EMPTY: DiscoveryIndex
 
-      def with: (?declared_types: Hash[untyped, Type::t], ?class_ivars: Hash[String, Hash[Symbol, Type::t]], ?class_cvars: Hash[String, Hash[Symbol, Type::t]], ?program_globals: Hash[Symbol, Type::t], ?discovered_classes: Hash[String, Type::Singleton], ?in_source_constants: Hash[String, Type::t], ?discovered_methods: Hash[String, Hash[Symbol, Symbol]], ?discovered_def_nodes: Hash[String, Hash[Symbol, untyped]], ?discovered_singleton_def_nodes: Hash[String, Hash[Symbol, untyped]], ?discovered_def_sources: Hash[String, Hash[Symbol, String]], ?discovered_method_visibilities: Hash[String, Hash[Symbol, Symbol]], ?discovered_superclasses: Hash[String, String], ?discovered_includes: Hash[String, Array[String]], ?discovered_class_sources: Hash[String, Set[String]], ?data_member_layouts: Hash[String, Array[Symbol]], ?struct_member_layouts: Hash[String, { members: Array[Symbol], keyword_init: bool }], ?param_inferred_types: Hash[[String, Symbol, Symbol], Hash[Symbol, Type::t]]) -> DiscoveryIndex
+      def with: (?declared_types: Hash[untyped, Type::t], ?class_ivars: Hash[String, Hash[Symbol, Type::t]], ?class_cvars: Hash[String, Hash[Symbol, Type::t]], ?program_globals: Hash[Symbol, Type::t], ?discovered_classes: Hash[String, Type::Singleton], ?in_source_constants: Hash[String, Type::t], ?discovered_methods: Hash[String, Hash[Symbol, Symbol]], ?discovered_def_nodes: Hash[String, Hash[Symbol, untyped]], ?discovered_singleton_def_nodes: Hash[String, Hash[Symbol, untyped]], ?discovered_def_sources: Hash[String, Hash[Symbol, String]], ?discovered_singleton_def_sources: Hash[String, Hash[Symbol, String]], ?discovered_method_visibilities: Hash[String, Hash[Symbol, Symbol]], ?discovered_superclasses: Hash[String, String], ?discovered_includes: Hash[String, Array[String]], ?discovered_class_sources: Hash[String, Set[String]], ?data_member_layouts: Hash[String, Array[Symbol]], ?struct_member_layouts: Hash[String, { members: Array[Symbol], keyword_init: bool }], ?param_inferred_types: Hash[[String, Symbol, Symbol], Hash[Symbol, Type::t]], ?run_generation: Object?) -> DiscoveryIndex
     end
 
     class IndexedKey
@@ -97,6 +104,9 @@ module Rigor
     def with_declaration_sourced_local: (String | Symbol name, Type::t type) -> Scope
     def with_local_declaration_mark: (String | Symbol name) -> Scope
     def declaration_sourced?: (Symbol kind, String | Symbol name) -> bool
+    def with_inferred_param_mark: (String | Symbol name) -> Scope
+    def without_inferred_param_mark: (String | Symbol name) -> Scope
+    def inferred_param?: (String | Symbol name) -> bool
     def forget_match_globals: () -> Scope
     def class_ivars_for: (String | Symbol? class_name) -> Hash[Symbol, Type::t]
     def class_cvars_for: (String | Symbol? class_name) -> Hash[Symbol, Type::t]
@@ -125,6 +135,7 @@ module Rigor
     def local_facts: (String | Symbol name, ?bucket: Symbol?) -> Array[Analysis::FactStore::Fact]
     def type_of: (untyped node, ?tracer: Inference::FallbackTracer?) -> Type::t
     def evaluate: (untyped node, ?tracer: Inference::FallbackTracer?) -> [Type::t, Scope]
+    def user_method_return: (untyped def_node, Type::t receiver, Array[Type::t] arg_types) -> Type::t?
     def join: (Scope other) -> Scope
     def ==: (untyped other) -> bool
     alias eql? ==

data/skills/rigor-ci-setup/SKILL.md

@@ -141,6 +141,16 @@ The exact recipe (the `BUNDLE_GEMFILE` wiring, the Dependabot entry) is in
   role.
 - **Determinism.** Add `--no-cache` in CI if you want each run independent
   of any persisted `.rigor/cache`.
+- **Cache persistence (opposite trade).** When the Rigor job's runtime
+  matters, persist `.rigor/cache` with the CI's cache facility. Current
+  Rigor detects CI and validates the restored cache by content hash
+  automatically (`cache.validation: auto`); on versions before the
+  `auto` default, **also set `RIGOR_STRICT_VALIDATION=1` on the job** —
+  without it a fresh checkout's regenerated stat tuples make the plugin
+  watch-glob cache slots read as stale on every run. A self-hosted
+  runner that reuses its workspace opts back into the faster stat check
+  with `cache.validation: stat`. Snippets: `rigor docs ci`
+  § "Persisting the analysis cache across runs".
 
 ## Verify
 

data/skills/rigor-editor-setup/SKILL.md

@@ -89,6 +89,17 @@ The manual chapter covers:
 - **Helix** (`languages.toml`)
 - **Emacs** (Eglot and lsp-mode)
 
+**The editors are not equally cheap to wire.** Neovim / Helix / Emacs
+are plain config snippets. **VS Code has no first-party Rigor
+extension yet** — its path means authoring and side-loading a minimal
+extension (a `LanguageClient` wrapper), which is a development task,
+not a `settings.json` edit. Say so *before* starting: the developer
+may prefer to wait for a first-class extension, and an autonomous
+agent should treat the VS Code path as a **user handoff** (report the
+manual's recipe; do not scaffold an unrequested extension). Phase 4's
+verification (live diagnostics, hover) also requires a human in front
+of the editor — an agent stops there and reports, for every editor.
+
 ### Phase 3 — apply the matching config
 
 Open the manual's **Editor wiring** section and apply the snippet for