rigortype 0.3.9 → 0.4.1

data/lib/rigor/sig_gen/generator.rb

@@ -13,9 +13,18 @@ require_relative "../source/literals"
 require_relative "../source/node_children"
 require_relative "../inference/def_return_typer"
 require_relative "../inference/scope_indexer"
+require_relative "../inference/module_function_state"
 require_relative "../inference/rbs_type_translator"
+require_relative "alias_index"
 require_relative "meta_class_shape"
 require_relative "rbs_validity"
+require_relative "classification"
+require_relative "effect_annotation"
+require_relative "declaration_equivalence"
+require_relative "inline_declarations"
+require_relative "layout_index"
+require_relative "method_candidate"
+require_relative "writer"
 
 module Rigor
   module SigGen
@@ -44,6 +53,15 @@ module Rigor
     # - A declared `void` return is never compared as a value type. It is the author's statement that the
     #   return is not part of the contract, which no inference can synthesize, so the method classifies
     #   `equivalent` carrying `void` itself as the declared spelling (#836; see {#declares_void?}).
+    # - A declared `untyped` return (the RBS `Bases::Any` spelling, including the one ADR-93 synthesizes for
+    #   a parameter-only inline `# @rbs` annotation) is the ABSENCE of a return statement, not the author's
+    #   word about it — the opposite of `void`. It is treated like no declaration at all: the inferred return
+    #   is proposed as `tighter-return`, carrying `untyped` as the declared spelling so `--diff` still shows a
+    #   declaration existed (#995; see {#declared_untyped?}).
+    # - A `tighter-return` over the class's own declaration replaces the return and nothing else: the rest of
+    #   the line is the declaration's, spelled as written, so `--overwrite` never changes which calls the
+    #   signature accepts. A declaration with more than one overload, or one spelled as an `alias`, is left
+    #   alone (#1436; see {#tighter_return_line}).
     # - A proposal that erases to an RBS literal never tightens an existing declaration: the declared type is
     #   the author's abstraction over the body and the literal is what it hides (#837; see
     #   {#pins_literal_over_declaration?}). A method with no declaration is unaffected — clause 1 still emits
@@ -62,11 +80,18 @@ module Rigor
       #   produced by {ObservationCollector}. An empty Hash (the default)
       #   means "no observations available; emit `untyped` for every
       #   parameter position" per ADR-5 clause 2.
-      def initialize(configuration:, paths:, observations: {}, include_private: false)
+      # @param overwrite — `--overwrite`: a member declared inline whose `sig/` copy disagrees is proposed as an
+      #   `inline-overwrite` of the whole member instead of refused (ADR-112 WD4).
+      def initialize(configuration:, paths:, observations: {}, include_private: false, effect_annotator: nil,
+                     overwrite: false)
         @configuration = configuration
+        @overwrite = overwrite
         @paths = paths
         @observations = normalize_observations(observations)
         @include_private = include_private
+        # ADR-103 WD9 — `nil` when the project's `effects:` opt-in is off, which is what keeps an
+        # effects-off run byte-identical to one from before the annotation slot was filled.
+        @effect_annotator = effect_annotator
         # Per-file scratch state. `analyse_file` resets each one to a fresh container for every file walked so
         # candidates from one file don't leak into another; initialising empty here gives downstream consumers
         # (`build_candidate`, `method_def_prefix`) a never-nil invariant without per-call-site defensive guards.
@@ -96,13 +121,99 @@ module Rigor
         resolved = resolve_paths(@paths)
         @environment = build_environment(resolved)
         candidates = resolved.flat_map { |path| analyse_file(path, @environment) }
-        demote_overridden_base_methods(
-          demote_unresolvable_superclasses(resolve_superclass_spellings(candidates))
+        annotate_effects(
+          demote_overridden_base_methods(
+            demote_unresolvable_superclasses(demote_inline_generic_classes(resolve_superclass_spellings(candidates)))
+          )
         )
       end
 
       private
 
+      # ADR-103 WD9 — the annotation-emission slot ADR-14 reserved, run LAST so a candidate a later
+      # demotion turns into a skip never carries an annotation it will not print. Only emittable rows are
+      # asked: an annotation is a claim attached to a line, and a row that produces no line makes none.
+      def annotate_effects(candidates)
+        return candidates if @effect_annotator.nil?
+
+        candidates.map do |candidate|
+          next candidate unless Classification::EMITTABLE.include?(candidate.classification)
+
+          annotations, reason = @effect_annotator.annotate(
+            class_name: candidate.class_name, method_name: candidate.method_name, kind: candidate.kind,
+            path: candidate.path
+          )
+          reason.nil? && annotations.empty? ? candidate : candidate.with_effect_annotation(annotations, reason)
+        end
+      end
+
+      # ADR-112 WD4 — nothing is written that would open a class an inline declaration makes generic (`# @rbs
+      # generic T`), or a namespace nested in one, in a file the project's `sig/` does not already declare it in;
+      # nor into a `sig/` declaration of the class whose type parameters are named otherwise (`class Box[U]`
+      # beside an inline `Box[T]`, which rbs accepts), where a copied `-> T` would name a parameter nothing binds.
+      #
+      # The writer spells a class header without type parameters, and rbs rejects a class whose declarations
+      # disagree on them (`GenericParameterMismatchError`): the class, and every class whose signature mentions
+      # it, fails its definition build and reads `Dynamic[top]` — while `rigor check` still exits 0. Skipping
+      # costs the generic class its `sig/` members; the inline declaration still binds when the source is
+      # analysed. A class `sig/` already declares is written into that declaration, whose parameters are the
+      # project's own.
+      def demote_inline_generic_classes(candidates)
+        generic = inline_declarations.generic_classes
+        return candidates if generic.empty?
+
+        layout = LayoutIndex.new(signature_paths: @configuration.signature_paths)
+        candidates.map do |candidate|
+          next candidate unless Classification::EMITTABLE.include?(candidate.classification)
+          next candidate unless unsafe_for_generic?(candidate.class_name, generic, layout)
+
+          demoted_candidate(candidate, :inline_generic_class)
+        end
+      end
+
+      def unsafe_for_generic?(class_name, generic, layout)
+        return false if class_name.nil?
+
+        file = layout.file_for(class_name)
+        return opens_generic_class?(class_name, generic) if file.nil?
+
+        generic.key?(class_name) && signature_type_params(file, class_name) != generic.fetch(class_name)
+      end
+
+      # The type parameter names `file` declares `class_name` with; nil when it cannot be read, which counts as
+      # a mismatch — writing into a declaration whose parameters are unknown is the unsafe direction.
+      def signature_type_params(file, class_name)
+        @signature_type_params ||= {}
+        @signature_type_params.fetch([file, class_name]) do
+          @signature_type_params[[file, class_name]] = read_signature_type_params(file, class_name)
+        end
+      end
+
+      def read_signature_type_params(file, class_name)
+        _buffer, _directives, decls = ::RBS::Parser.parse_signature(File.read(file))
+        find_declaration(decls, [], class_name)&.type_params&.map(&:name)
+      rescue StandardError
+        nil
+      end
+
+      def find_declaration(decls, prefix, class_name)
+        decls.each do |decl|
+          next unless decl.is_a?(::RBS::AST::Declarations::Class) || decl.is_a?(::RBS::AST::Declarations::Module)
+
+          name = (prefix + [decl.name.to_s.delete_prefix("::")]).join("::")
+          return decl if name == class_name
+
+          found = find_declaration(decl.members, name.split("::"), class_name)
+          return found if found
+        end
+        nil
+      end
+
+      def opens_generic_class?(class_name, generic)
+        segments = class_name.split("::")
+        (1..segments.size).any? { |n| generic.key?(segments.first(n).join("::")) }
+      end
+
       # Issue #744 — a base class's method is NOT emitted when a project subclass overrides it and the
       # override is not emitted itself.
       #
@@ -229,7 +340,8 @@ module Rigor
           inferred_return: candidate.inferred_return, declared_return_rbs: candidate.declared_return_rbs,
           rbs: candidate.rbs, skip_reason: candidate.skip_reason,
           namespace_kinds: candidate.namespace_kinds, class_shells: candidate.class_shells,
-          class_superclasses: superclasses
+          class_superclasses: superclasses, declared_rbs: candidate.declared_rbs,
+          declared_annotations: candidate.declared_annotations
         )
       end
 
@@ -353,7 +465,7 @@ module Rigor
         @class_superclasses = {}
         @meta_layouts = collect_meta_layouts(scope_index)
         register_meta_classes
-        defs = collect_method_definitions(parse_result.value)
+        defs = collect_method_definitions(parse_result.value, scope_index)
         # Candidate construction freezes the per-file maps above (see {#build_candidate}), so every registration
         # pass has to be finished before the first `build_candidate` call. Meta members lead the RETURNED order —
         # a value class's members and constructors read first, ahead of the methods its block body defines.
@@ -386,7 +498,8 @@ module Rigor
       # - `@module_function_methods` records `(class_name, method_name)` pairs where a `module_function` (no
       #   args) call preceded the `def` inside a module body. The renderer emits `def self?.name` for these, the
       #   RBS spelling that matches the dual instance + singleton dispatch the runtime produces.
-      def collect_method_definitions(root)
+      def collect_method_definitions(root, scope_index)
+        @declared_types = scope_index[root].declared_types
         out = []
         walk_defs(root, [], false, false, out)
         out
@@ -431,6 +544,11 @@ module Rigor
       # `prefix` stays the nesting the header is WRITTEN in for {#record_superclass}: `::` re-anchors the
       # declaration, not the superclass expression beside it, which Ruby still evaluates in the enclosing cref.
       def descend_into_namespace?(node, prefix, out)
+        # Issue #1518 — a `class self::X` / `module self::X` the indexer declined (`self` is opaque, as under
+        # `REGISTRY.first.class_eval`) names no class, so its body must not be written out under the lexical
+        # `X`. The indexer's identity table is the single source of that decision.
+        return true if declined_self_header?(node)
+
         child_prefix = Source::ConstantPath.declaration_prefix(prefix, node.constant_path)
         return false unless child_prefix
 
@@ -441,6 +559,12 @@ module Rigor
         true
       end
 
+      def declined_self_header?(node)
+        path = node.constant_path
+        path.is_a?(Prism::ConstantPathNode) && path.parent.is_a?(Prism::SelfNode) &&
+          !@declared_types.key?(path)
+      end
+
       # ADR-14: a generated subclass declaration MUST carry its superclass, or the sidecar `sig/` misrepresents
       # the class (inherited members vanish → receiver dispatch degrades to `Dynamic`) and, worse, a nested
       # reference to an inherited type re-declares the class as a bare namespace on the RBS side and can
@@ -551,29 +675,22 @@ module Rigor
         walk_defs(namespace_node.body, prefix, false, false, out)
       end
 
+      # The directive's reach is {Inference::ModuleFunctionState.each_sig_gen_statement}.
       def walk_statements(stmts_node, prefix, in_singleton_class, module_function_active, out)
-        stmts_node.body.each do |stmt|
-          if module_function_directive?(stmt)
-            module_function_active = true
-            next
-          end
-          walk_defs(stmt, prefix, in_singleton_class, module_function_active, out)
+        Inference::ModuleFunctionState.each_sig_gen_statement(stmts_node.body,
+                                                              module_function_active) do |stmt, active|
+          walk_defs(stmt, prefix, in_singleton_class, active, out)
         end
       end
 
-      def module_function_directive?(node)
-        return false unless node.is_a?(Prism::CallNode)
-        return false unless node.name == :module_function && node.receiver.nil?
-
-        (node.arguments&.arguments || []).empty?
-      end
-
       def collect_def_node(node, prefix, in_singleton_class, module_function_active, out)
         return if prefix.empty?
 
         kind = node.receiver.is_a?(Prism::SelfNode) || in_singleton_class ? :singleton : :instance
         class_name = prefix.join("::")
-        @module_function_methods << [class_name, node.name] if module_function_active && kind == :instance
+        if Inference::ModuleFunctionState.sig_gen_module_function?(module_function_active, kind)
+          @module_function_methods << [class_name, node.name]
+        end
         out << [node, class_name, kind]
       end
 
@@ -678,10 +795,22 @@ module Rigor
       # `ObservationCollector`'s `.new` → `:initialize` routing), positional and keyword arg types come from the
       # per-position / per-keyword union of observed types; otherwise every position keeps `untyped` per ADR-5
       # clause 2.
-      def initialize_stub_candidate(path, def_node, class_name)
+      #
+      # Issue #1436 — a constructor the class's own `sig/` already declares is `equivalent`, like any other
+      # declared member, unless the stub clears an `untyped` the declaration still carries: that is the
+      # `--params=observed` upgrade `--overwrite` applies ({Writer.fewer_untyped?}, the writer's own test).
+      # Without observations the stub is all `untyped` and never qualifies, so it is never listed as new.
+      def initialize_stub_candidate(path, def_node, class_name, scope)
         params = def_node.parameters
         rbs = "def initialize: (#{render_param_list(params, class_name, :initialize)})" \
               "#{block_signature_suffix(params)} -> void"
+        method_def = lookup_existing_method(class_name, :initialize, :instance, scope&.environment, scope)
+        member = signature_member(method_def, class_name)
+        if member && !Writer.fewer_untyped?(rbs, member.location&.source.to_s)
+          declared = declares_void?(method_def) ? VOID_RETURN_RBS : build_declared_return(method_def)&.erase_to_rbs
+          return equivalent(path, def_node, class_name, :instance, Type::Combinator.untyped, declared)
+        end
+
         build_candidate(
           path: path, class_name: class_name, method_name: :initialize,
           kind: :instance, classification: Classification::NEW_METHOD,
@@ -706,12 +835,12 @@ module Rigor
 
         observations = arity_matched_observations(class_name, method_name, params)
         parts = []
-        params.requireds.each_index { |i| parts << positional_type(observations, i, "") }
+        params.requireds.each_index { |i| parts << positional_type(observations, i, "", class_name) }
         offset = params.requireds.size
-        params.optionals.each_index { |i| parts << positional_type(observations, offset + i, "?") }
+        params.optionals.each_index { |i| parts << positional_type(observations, offset + i, "?", class_name) }
         parts << "*untyped" if params.rest
         parts.concat(Array.new(params.posts.size, "untyped"))
-        params.keywords.each { |kw| parts << render_keyword_param(kw, observations) }
+        params.keywords.each { |kw| parts << render_keyword_param(kw, observations, class_name) }
         parts.concat(keyword_rest_parts(params))
         parts.join(", ")
       end
@@ -761,15 +890,15 @@ module Rigor
 
       # A bare union is a valid positional type in RBS (`(String | Integer, ?String | Integer)`), so unlike the
       # return position it is not parenthesised.
-      def positional_type(observations, index, prefix)
+      def positional_type(observations, index, prefix, owner = nil)
         types = observations.filter_map { |obs| obs.positional[index] }
-        "#{prefix}#{union_erase(types)}"
+        "#{prefix}#{union_erase(types, owner: owner)}"
       end
 
-      def render_keyword_param(keyword, observations)
+      def render_keyword_param(keyword, observations, owner = nil)
         optional_marker = keyword.is_a?(Prism::OptionalKeywordParameterNode) ? "?" : ""
         types = observations.filter_map { |obs| obs.keyword[keyword.name] }
-        rendered = types.empty? ? "untyped" : paren_wrap_union(union_erase(types))
+        rendered = types.empty? ? "untyped" : paren_wrap_union(union_erase(types, owner: owner))
         "#{optional_marker}#{keyword.name}: #{rendered}"
       end
 
@@ -789,7 +918,15 @@ module Rigor
       def classify_def(path, def_node, class_name, kind, scope_index)
         return nil if visibility_excludes?(def_node, class_name, kind, scope_index)
         return nil if initialize_excludes?(def_node, kind)
-        return initialize_stub_candidate(path, def_node, class_name) if non_trivial_initialize?(def_node, kind)
+
+        inline = inline_declarations.lookup(path, class_name, def_node.name, kind)
+        if inline
+          return skipped(path, def_node, class_name, kind, :inline_declared) if skip_inline_declared?
+          return inline_def_candidate(path, def_node, class_name, kind, scope_index, inline) if inline.declared?
+        end
+        if non_trivial_initialize?(def_node, kind)
+          return initialize_stub_candidate(path, def_node, class_name, scope_index[def_node])
+        end
 
         inferred = infer_return_type(def_node, scope_index)
         return skipped(path, def_node, class_name, kind, :untyped_return) if inferred.nil? || dynamic_top?(inferred)
@@ -804,6 +941,242 @@ module Rigor
         end
       end
 
+      # ADR-112 WD4 — the inline declarations of every analysed file, read once per run. See
+      # {InlineDeclarations} for why the synthesized text rather than the environment.
+      def inline_declarations
+        @inline_declarations ||= InlineDeclarations.build(@environment)
+      end
+
+      def skip_inline_declared?
+        @configuration.sig_gen_inline_declared == :skip
+      end
+
+      # ADR-112 WD4 — a `def` the author declared inline is written from that declaration, as rbs-inline reads it,
+      # not from what the body infers: `rigor check` reads the `sig/` member beside the inline one (ADR-112 WD5),
+      # so a line built from inference (`untyped` parameters, a return the body happens to prove) would override
+      # or contradict the contract the author wrote beside the code.
+      #
+      # The one inferred part is a return the author left unwritten (`# @rbs name: String`, no `return:`) —
+      # ADR-107's mixed provenance, parameters authored and return generated — filled from the body; a body that
+      # types as `untyped` there is skipped exactly as an undeclared one is. `initialize` returns `void` by
+      # definition, whatever its last expression is.
+      def inline_def_candidate(path, def_node, class_name, kind, scope_index, inline)
+        types = inline.method_types
+        return_defaulted = inline.return_inferred
+        if return_defaulted && initialize_def?(def_node, kind)
+          void = ::RBS::Types::Bases::Void.new(location: nil)
+          types = types.map { |mt| defaulted_return?(mt) ? with_return_type(mt, void) : mt }
+          return_defaulted = false
+        end
+
+        scope = scope_index[def_node]
+        method_def = lookup_existing_method(class_name, def_node.name, kind, scope&.environment, scope)
+        head = "#{method_def_prefix(class_name, def_node.name, kind)}#{def_node.name}: "
+        if return_defaulted
+          return mixed_provenance_candidate(path, def_node, class_name, kind, scope_index, inline, method_def, head)
+        end
+
+        inline_candidate(path, class_name, def_node.name, kind, head + types.join(" | "), inline, method_def)
+      end
+
+      # A parameter-only annotation (`# @rbs name: String`, no `return:`): parameters authored, return inferred.
+      # Only the authored half is weighed against `sig/`. When the parameters differ the method is refused, even
+      # under `--overwrite` — the body is typed under the parameters the environment binds, which are `sig/`'s
+      # once it declares the member, so a return inferred for the new line would describe parameters about to
+      # change. When they match, the return is an ordinary inferred proposal: {#compare_against_declared}
+      # leaves a declared `void`, a deliberately wider type and a declined literal alone, and proposes a
+      # strictly narrower return as `tighter-return`, spelled with the authored parameters.
+      def mixed_provenance_candidate(path, def_node, class_name, kind, scope_index, inline, method_def, head) # rubocop:disable Metrics/ParameterLists
+        types = inline.method_types
+        existing = signature_member(method_def, class_name)
+        if existing && parameters_differ?(existing, types, def_node.name, class_name)
+          return skipped(path, def_node, class_name, kind, :inline_differs)
+        end
+
+        inferred, overloads = inferred_overloads(def_node, scope_index, class_name, types)
+        return skipped(path, def_node, class_name, kind, :untyped_return) if inferred.nil?
+
+        rbs = head + overloads.join(" | ")
+        if existing && annotations_present?(existing, inline) && existing_types(existing, def_node.name)
+          return compare_against_declared(path, def_node, class_name, kind, inferred, method_def, rendered: rbs)
+        end
+
+        inline_candidate(path, class_name, def_node.name, kind, rbs, inline, method_def, inferred)
+      end
+
+      # `[inferred return, overload strings]`, or `[nil, nil]` when the body types as `untyped`.
+      def inferred_overloads(def_node, scope_index, class_name, types)
+        inferred = infer_return_type(def_node, scope_index)
+        return [nil, nil] if inferred.nil? || dynamic_top?(inferred)
+
+        [inferred, with_defaulted_return(types, paren_wrap_union(elaborated_rbs(inferred, owner: class_name)))]
+      end
+
+      # Whether a `sig/` member's overloads, returns aside, differ from the inline declaration's. Such a member is
+      # refused even under `--overwrite` when the inline return is to be inferred (see {#inline_def_candidate});
+      # deleting the `sig/` member lets the next run infer it under the inline parameters.
+      def parameters_differ?(existing, types, method_name, class_name)
+        written = existing_types(existing, method_name)
+        return false if written.nil?
+
+        !equivalence(class_name).same_parameters?(written, types)
+      end
+
+      def initialize_def?(def_node, kind)
+        kind == :instance && def_node.name == :initialize
+      end
+
+      def defaulted_return?(method_type)
+        method_type.type.return_type.is_a?(::RBS::Types::Bases::Any)
+      end
+
+      def with_return_type(method_type, return_type)
+        method_type.update(type: method_type.type.with_return_type(return_type))
+      end
+
+      # A class name no project declares, standing in for the inferred return while `RBS::MethodType#to_s` spells
+      # the rest of an overload, so the return itself keeps sig-gen's own spelling (`[Float, String]`, a folded
+      # alias) rather than being re-spelled through a parse.
+      INFERRED_RETURN_PLACEHOLDER = "Rigor__SigGenInferredReturn"
+      private_constant :INFERRED_RETURN_PLACEHOLDER
+
+      # Each overload whose return rbs-inline defaulted to `untyped` takes `returned` (already spelled for a
+      # return position); the rest stay as written.
+      def with_defaulted_return(method_types, returned)
+        method_types.map do |method_type|
+          defaulted_return?(method_type) ? spell_with_return(method_type, returned) : method_type.to_s
+        end
+      end
+
+      # One overload spelled with `returned` (already spelled for a return position) as its return.
+      def spell_with_return(method_type, returned)
+        placeholder = ::RBS::Parser.parse_type(INFERRED_RETURN_PLACEHOLDER)
+        with_return_type(method_type, placeholder).to_s.sub(/-> #{INFERRED_RETURN_PLACEHOLDER}\z/o, "-> #{returned}")
+      end
+
+      # Classifies an inline-declared member's `rbs` line against what `sig/` already says for it (ADR-112 WD4, as
+      # decided on #1422):
+      #
+      # - nothing on this class itself (or only the inline declaration) — `new-method`;
+      # - the same types, and every annotation the author wrote inline — `equivalent`;
+      # - anything else — the two declarations disagree, and neither is presumed right. Without `--overwrite`
+      #   the member is REFUSED (`sig.skipped.inline-differs`): nothing is written, and `--write` / `--check`
+      #   exit 1 until a person reconciles them. With `--overwrite` it is `inline-overwrite`, which replaces the
+      #   whole `sig/` member with the inline line — never a mix of the two, whose slots (and type variables)
+      #   need not correspond.
+      def inline_candidate(path, class_name, method_name, kind, rbs, inline, method_def, inferred = nil) # rubocop:disable Metrics/ParameterLists
+        fields = { path: path, class_name: class_name, method_name: method_name, kind: kind,
+                   inferred_return: inferred }
+        existing = signature_member(method_def, class_name)
+        if existing.nil?
+          build_candidate(**fields, classification: Classification::NEW_METHOD, rbs: rbs,
+                                    declared_annotations: inline.annotation_lines)
+        elsif current_copy?(existing, rbs, inline, method_name, class_name)
+          build_candidate(**fields, classification: Classification::EQUIVALENT)
+        elsif @overwrite
+          # An `attr_*` member is replaced in its own spelling, by the inline attribute's.
+          line = attr_member?(existing) && inline.attr_line ? inline.attr_line : rbs
+          build_candidate(**fields, classification: Classification::INLINE_OVERWRITE, rbs: line,
+                                    declared_annotations: inline.annotation_lines,
+                                    declared_rbs: squish(existing.location&.source))
+        else
+          build_candidate(**fields, classification: Classification::SKIPPED, skip_reason: :inline_differs)
+        end
+      end
+
+      # The member a project `.rbs` declares for `class_name` itself — not an ancestor's, and not the inline
+      # declaration, whose buffer is the synthesizer's `virtual:` one. An `overloading?` member (`def x: … |
+      # ...`) is not a counterpart either: it adds overloads to the inline declaration rather than restating
+      # it, and sig-gen leaves it alone.
+      def signature_member(method_def, class_name)
+        return nil if method_def.nil?
+
+        method_def.defs.filter_map do |type_def|
+          next unless type_def.defined_in.to_s.delete_prefix("::") == class_name
+
+          member = type_def.member
+          next if member.respond_to?(:overloading?) && member.overloading?
+
+          member unless member.location&.buffer&.name.to_s.start_with?("virtual:")
+        end.first
+      end
+
+      # The two declarations are compared as types ({DeclarationEquivalence}): parameter names, union spelling
+      # and a leading `::` that resolves to the same constant do not count; overload order does. The copy must
+      # also carry every annotation the author wrote inline. A `sig/` member whose text is unavailable is left
+      # as it is rather than refused for good.
+      def current_copy?(member, rbs, inline, method_name, class_name)
+        written = existing_types(member, method_name)
+        mine = member_types(rbs)
+        return true if written.nil? || mine.nil?
+
+        equivalence(class_name).same?(written, mine) && annotations_present?(member, inline)
+      end
+
+      def annotations_present?(member, inline)
+        (inline.annotations - member.annotations.map { |annotation| annotation.string.to_s.strip }).empty?
+      end
+
+      def attr_member?(member)
+        member.is_a?(::RBS::AST::Members::AttrReader) || member.is_a?(::RBS::AST::Members::AttrWriter) ||
+          member.is_a?(::RBS::AST::Members::AttrAccessor)
+      end
+
+      # The overloads a `sig/` member declares for `method_name`: a `def`'s, parsed from its own text; an
+      # attribute's reader (`() -> T`) or writer (`(T) -> T`), from its type.
+      def existing_types(member, method_name)
+        return member_types(member.location&.source) if member.is_a?(::RBS::AST::Members::MethodDefinition)
+        return nil unless attr_member?(member)
+
+        shape = method_name.to_s.end_with?("=") ? "(#{member.type}) -> #{member.type}" : "() -> #{member.type}"
+        [::RBS::Parser.parse_method_type(shape)]
+      rescue ::RBS::BaseError
+        nil
+      end
+
+      def equivalence(class_name)
+        @equivalence ||= {}
+        @equivalence[class_name] ||= DeclarationEquivalence.new(resolve: type_name_resolver(class_name))
+      end
+
+      # A type name as written, resolved the way RBS resolves it inside `class_name`'s declaration: an absolute
+      # `::Foo` is `Foo`; a relative `Foo` is the innermost `…::Foo` the environment knows, so inside `module NS`
+      # it is `NS::Foo` when `NS` declares one, and `::Foo` only when it does not.
+      def type_name_resolver(class_name)
+        nesting = class_name.split("::")
+        lambda do |name|
+          next name.delete_prefix("::") if name.start_with?("::")
+
+          nesting.size.downto(1).map { |n| (nesting.first(n) + [name]).join("::") }
+                 .find { |candidate| class_known?(candidate) } || name
+        end
+      end
+
+      def class_known?(name)
+        @class_known ||= {}
+        @class_known.fetch(name) { @class_known[name] = Reflection.rbs_class_known?(name, environment: @environment) }
+      end
+
+      # A member line's overloads, parsed with type names unresolved so the two sides compare as written.
+      def member_types(source)
+        member_overloads(source)&.map(&:method_type)
+      end
+
+      # The same, with each overload's own annotations (`%a{pure} (Integer) -> String`).
+      def member_overloads(source)
+        return nil if source.nil?
+
+        _buffer, _directives, decls = ::RBS::Parser.parse_signature("class Rigor__SigGenProbe\n#{source}\nend\n")
+        parsed = decls.first&.members&.first
+        parsed.is_a?(::RBS::AST::Members::MethodDefinition) ? parsed.overloads : nil
+      rescue ::RBS::BaseError
+        nil
+      end
+
+      def squish(text)
+        text.to_s.gsub(/\s+/, " ").strip
+      end
+
       # Mirrors the `def.return-type-mismatch` rule's body-type extraction: type the implicit-return expression
       # under the scope the indexer associated with the body. The parameter bindings (typed `untyped` per the
       # indexer's default) come from `with_local` inside `StatementEvaluator`; the result is the carrier the
@@ -813,9 +1186,10 @@ module Rigor
       # types with the implicit-return expression's type. The earlier MVP only typed the implicit-return path,
       # which routinely produced single-branch artefacts like `parse_options: () -> nil` (the actual runtime
       # return is `options | nil`) or `find: () -> V` (actually `V | nil` via `return nil unless ...`). The walk
-      # excludes nested `DefNode` / lambda / block scopes whose returns belong to different methods. Delegates
-      # to {Rigor::Inference::DefReturnTyper} — the same body-typing + explicit-return-union the `rigor
-      # annotate` def-line annotator uses.
+      # includes a `return` inside an ordinary block, which exits the method, and excludes the
+      # {Rigor::Inference::ReturnBarrier} bodies — nested `def`, lambda, `define_method` — whose returns belong to a
+      # different method (issue #1382). Delegates to {Rigor::Inference::DefReturnTyper} — the same body-typing +
+      # explicit-return-union the `rigor annotate` def-line annotator uses.
       def infer_return_type(def_node, scope_index)
         Inference::DefReturnTyper.call(def_node, scope_index)
       end
@@ -858,10 +1232,16 @@ module Rigor
       VOID_RETURN_RBS = "void"
       private_constant :VOID_RETURN_RBS
 
-      def compare_against_declared(path, def_node, class_name, kind, inferred, method_def)
+      # @param rendered — the line a proposal is spelled as when it is not the ordinary inferred one: a
+      #   parameter-only inline annotation keeps its authored parameters ({#mixed_provenance_candidate}).
+      def compare_against_declared(path, def_node, class_name, kind, inferred, method_def, rendered: nil)
         return equivalent(path, def_node, class_name, kind, inferred, VOID_RETURN_RBS) if declares_void?(method_def)
 
         declared = build_declared_return(method_def)
+        if declared_untyped?(declared)
+          return declared_untyped_candidate(path, def_node, class_name, kind, inferred, method_def, rendered: rendered)
+        end
+
         declared_rbs = declared&.erase_to_rbs
         inferred_rbs = inferred.erase_to_rbs
 
@@ -873,6 +1253,17 @@ module Rigor
           return equivalent(path, def_node, class_name, kind, inferred, declared_rbs)
         end
 
+        tighter_return_candidate(path, def_node, class_name, kind, inferred, method_def, declared_rbs, rendered)
+      end
+
+      # Both tightening branches end here. The proposal is the declaration with its return replaced
+      # ({#tighter_return_line}); when there is no single declared overload to replace it in, the method is
+      # `equivalent` — the declaration stands, as it does for any narrowing the generator declines. `declared_rbs`
+      # carries the class's own declaration so `--diff` and `--check` show the line the proposal replaces.
+      def tighter_return_candidate(path, def_node, class_name, kind, inferred, method_def, declared_return, rendered) # rubocop:disable Metrics/ParameterLists
+        line = rendered || tighter_return_line(def_node, method_def, class_name, kind, inferred)
+        return equivalent(path, def_node, class_name, kind, inferred, declared_return) if line.nil?
+
         build_candidate(
           path: path,
           class_name: class_name,
@@ -880,11 +1271,68 @@ module Rigor
           kind: kind,
           classification: Classification::TIGHTER_RETURN,
           inferred_return: inferred,
-          declared_return_rbs: declared_rbs,
-          rbs: render_rbs_line(def_node, inferred, class_name, kind)
+          declared_return_rbs: declared_return,
+          declared_rbs: declared_line(method_def, class_name),
+          rbs: line
         )
       end
 
+      # Issue #1436 — a `tighter-return` changes the return and only the return. It used to be rendered like a
+      # new method, from the `def`'s runtime shape: every parameter `untyped`, `(?)` spelled out as
+      # `(*untyped)`, names and block types dropped. Under `--overwrite` that replaced a declared `(Integer x)`
+      # with `(untyped)` — a change to which calls the signature accepts, made by a proposal that claims to be
+      # about the return. The class's own declaration is kept whole instead: its visibility, the overload's
+      # annotations, type parameters, parameters and block, with only the return replaced.
+      #
+      # Three shapes are declined (`nil`):
+      # - several overloads. The body is typed once, so the inferred return covers every overload together and
+      #   says nothing about which overload returns what: collapsing them into one line would drop the
+      #   overloads, and giving each the joint return would widen the overloads the author wrote narrower.
+      # - a name the class's own `sig/` spells as an `alias`. Its parameters are the aliased method's, and a
+      #   proposal would read as a rewrite of that method's line rather than of the alias. An alias only an
+      #   ancestor declares takes the override path below, like any other ancestor declaration.
+      # - nothing else: when only an ancestor declares the method, the proposal is a new override on this
+      #   class, and is rendered from the `def`'s own shape like any new method. The ancestor's parameters
+      #   describe the ancestor's `def`, not this one, which may take other arguments (ADR-14 clause 2).
+      def tighter_return_line(def_node, method_def, class_name, kind, inferred)
+        member = signature_member(method_def, class_name)
+        return render_rbs_line(def_node, inferred, class_name, kind) if member.nil?
+        return nil if method_def.alias_of
+
+        overload = sole_declared_overload(member, method_def, def_node.name)
+        return nil if overload.nil?
+
+        returned = paren_wrap_union(elaborated_rbs(inferred, owner: class_name))
+        annotations = overload.annotations.map { |a| "#{a.location&.source || "%a{#{a.string}}"} " }.join
+        visibility = member.respond_to?(:visibility) && member.visibility ? "#{member.visibility} " : ""
+        "#{visibility}#{method_def_prefix(class_name, def_node.name, kind)}#{def_node.name}: " \
+          "#{annotations}#{spell_with_return(overload.method_type, returned)}"
+      end
+
+      # The one overload the class's own `sig/` member declares, parsed from its text with its annotations so it
+      # keeps the spelling the author wrote (`Integer`, not the resolved `::Integer`). An attribute declares one
+      # implicitly and carries no overload annotations.
+      def sole_declared_overload(member, method_def, method_name)
+        return nil unless method_def.method_types.size == 1
+
+        overloads =
+          if member.is_a?(::RBS::AST::Members::MethodDefinition)
+            member_overloads(member.location&.source)
+          else
+            existing_types(member, method_name)&.map do |method_type|
+              ::RBS::AST::Members::MethodDefinition::Overload.new(method_type: method_type, annotations: [])
+            end
+          end
+        overloads&.size == 1 ? overloads.first : nil
+      end
+
+      # The class's own declaration, as the `-` line of `--diff` and `--check` shows it. A method only an
+      # ancestor declares has none: the proposal adds an override rather than replacing a line.
+      def declared_line(method_def, class_name)
+        source = signature_member(method_def, class_name)&.location&.source
+        source && squish(source)
+      end
+
       # Issue #836 — a declared `void` is return INTENT, never a wide value type waiting to be narrowed, so it
       # is not compared against the body at all.
       #
@@ -907,6 +1355,27 @@ module Rigor
         method_def.method_types.any? { |mt| mt.type.return_type.is_a?(RBS::Types::Bases::Void) }
       end
 
+      # Issue #995 — a declared `untyped` (RBS `Bases::Any`, translated by
+      # {Inference::RbsTypeTranslator} to `Type::Dynamic`) says nothing at all, unlike `void` (#836), which is
+      # the author's word that the value is not part of the contract. `tighter?`'s acceptance check cannot
+      # tell the two apart — `untyped` accepts and is accepted by everything, so its backward check, which
+      # exists to refuse a declaration that carries real information the inferred form would narrow, also
+      # refused this one — and the candidate fell into `equivalent`: neither emitted nor counted among the
+      # skips. ADR-93's inline `# @rbs param: Type` annotation (no return clause) synthesizes exactly this
+      # spelling for every method it documents, so the silent drop hit the parameter-annotated, return-bare
+      # shape ADR-14 exists to help.
+      def declared_untyped?(declared)
+        declared.is_a?(Type::Dynamic)
+      end
+
+      # Proposed without {#compare_against_declared}'s tightening guards: a declared `untyped` return carries no
+      # information to weigh {#tighter?} or {#literal_decline?} against, the same position a method with no
+      # declaration at all is in. The line is built as for any tightening ({#tighter_return_line}), and
+      # `declared_return_rbs` carries `"untyped"` so the `[tighter, was: untyped]` print tag says one existed.
+      def declared_untyped_candidate(path, def_node, class_name, kind, inferred, method_def, rendered: nil)
+        tighter_return_candidate(path, def_node, class_name, kind, inferred, method_def, "untyped", rendered)
+      end
+
       def build_declared_return(method_def)
         translated = method_def.method_types.filter_map { |mt| translate_method_type_return(mt) }
         return nil if translated.empty?
@@ -914,10 +1383,19 @@ module Rigor
         translated.size == 1 ? translated.first : Type::Combinator.union(*translated)
       end
 
+      # `alias_expander:` matters here as much as it does at any dispatch site (see
+      # {Inference::RbsTypeTranslator}'s own doc comment): without it, a declared return spelled as a
+      # project alias (`Type::t`, `Environment::ordering`, `Inference::closure_classification`) degrades
+      # to `Dynamic[Top]` exactly like a bare `untyped` would, and {#declared_untyped?} cannot tell an
+      # author's meaningful alias apart from an absent declaration. That collapsed a well-typed, already
+      # exact declaration into a spurious {#declared_untyped_candidate} the moment #995 made "declared
+      # untyped" a proposable position — the ADR-107 G3 gate caught it on this repo's own `sig/` tree
+      # (`Environment#class_ordering`'s `-> ordering` and every `-> Type::t` return in `type.rbs` /
+      # `inference.rbs` / `scope.rbs`).
       def translate_method_type_return(method_type)
         Inference::RbsTypeTranslator.translate(
           method_type.type.return_type,
-          self_type: nil, instance_type: nil, type_vars: {}
+          self_type: nil, instance_type: nil, type_vars: {}, alias_expander: @environment&.rbs_loader
         )
       rescue StandardError
         nil
@@ -1097,15 +1575,54 @@ module Rigor
         params = def_node.parameters
         head = "(#{render_param_list(params, class_name, def_node.name)})#{block_signature_suffix(params)}"
         prefix = method_def_prefix(class_name, def_node.name, kind)
-        "#{prefix}#{def_node.name}: #{head} -> #{paren_wrap_union(elaborated_rbs(inferred))}"
+        "#{prefix}#{def_node.name}: #{head} -> #{paren_wrap_union(elaborated_rbs(inferred, owner: class_name))}"
       end
 
       # Routes the inferred carrier through {TypeElaborator} so bare generic nominals (`Array` / `Hash` / `Set`
       # / `Range` / `Enumerable`) get their `untyped` type parameters filled in before erasing to RBS. The
       # elaborator consults the class's RBS-declared type-parameter list via
       # `Reflection.class_type_param_names`.
-      def elaborated_rbs(type)
-        TypeElaborator.elaborate(type, environment: @environment).erase_to_rbs
+      # `owner:` is the class or module the rendered member belongs to. {AliasIndex} needs it to judge whether
+      # a matching alias is one this reader would expect to see; a call site that cannot supply it renders the
+      # type unfolded, which is the same output as before #1002.
+      def elaborated_rbs(type, owner: nil)
+        alias_index.fold(TypeElaborator.elaborate(type, environment: @environment).erase_to_rbs, owner)
+      end
+
+      # Issue #1002 — the reverse of {#translate_method_type_return}'s `alias_expander:`. Folding happens here,
+      # at the single seam every rendered type passes through (`render_rbs_line`, `union_erase` for parameter
+      # and ivar positions, the attr path), so `--print`, `--diff`, `--write` and `--format=json` cannot drift
+      # from one another: they all read the `rbs` string a candidate was built with. Deliberately NOT in
+      # {Type::Union#erase_to_rbs} — that carrier method is the type model's RBS surface, shared with
+      # diagnostics, `rigor type-of` and the engine's own comparisons, and none of those should start naming a
+      # project alias. Sig-gen's rendering preference is a CLI concern and stays on the CLI side.
+      def alias_index
+        @alias_index ||= AliasIndex.build(
+          environment: @environment,
+          signature_paths: project_signature_paths,
+          excluded_paths: plugin_signature_paths
+        )
+      end
+
+      # The project's OWN signature paths, resolved exactly as `Environment.for_project` resolves its
+      # `resolved_paths` — the configured list, or `<root>/sig` when the project configured none. The
+      # loader's `signature_paths` is NOT the same list: it also carries plugin signature paths, gem `sig/`
+      # directories discovered under the project's bundle, the `rbs collection` tree and Rigor's own gem
+      # overlays, none of which declare vocabulary this project chose.
+      def project_signature_paths
+        configured = @configuration.signature_paths
+        return configured unless configured.nil?
+
+        default = Pathname(Dir.pwd) / "sig"
+        default.directory? ? [default] : []
+      end
+
+      # A loaded plugin's own signature directory is the plugin's vocabulary, not the project's, whether the
+      # plugin tier contributed it or the project wired it into `signature_paths:` itself (#697).
+      def plugin_signature_paths
+        @environment&.plugin_registry&.signature_paths || []
+      rescue StandardError
+        []
       end
 
       # RBS / Steep require return-position unions to be parenthesised when they appear bare at the top level of
@@ -1131,15 +1648,15 @@ module Rigor
         false
       end
 
-      def union_erase(types)
+      def union_erase(types, owner: nil)
         return "untyped" if types.empty?
-        return elaborated_rbs(types.first) if types.size == 1
+        return elaborated_rbs(types.first, owner: owner) if types.size == 1
 
         # `Type::Combinator.union` dedupes by structural type equality. The carrier-level `erase_to_rbs` now
         # absorbs `untyped` members and dedupes the post-erase strings (`String | String` → `String` for
         # distinct `Constant<"Alice">` / `Constant<"Bob">` envelopes), so the sig-gen layer only needs to
         # elaborate bare generics before erasing.
-        elaborated_rbs(Type::Combinator.union(*types))
+        elaborated_rbs(Type::Combinator.union(*types), owner: owner)
       end
 
       # ADR-14 slice 4 — `attr_reader` / `attr_writer` / `attr_accessor` recognition. Each Symbol-named entry in
@@ -1155,6 +1672,7 @@ module Rigor
         attr_writer: [:writer],
         attr_accessor: %i[reader writer]
       }.freeze
+      Ractor.make_shareable(ATTR_KINDS)
       private_constant :ATTR_KINDS
 
       # Per-file context the attr_* walker threads through its recursive descent. Keeps parameter lists in
@@ -1363,6 +1881,12 @@ module Rigor
       end
 
       def build_attr_candidate(class_name, method_name, variant, ivar_type, ctx)
+        inline = inline_declarations.lookup(ctx.path, class_name, method_name, :instance)
+        if inline
+          return attr_skipped(ctx.path, class_name, method_name, :inline_declared) if skip_inline_declared?
+          return inline_attr_candidate(class_name, method_name, inline, ctx) if inline.declared?
+        end
+
         if ivar_type.nil? || dynamic_top?(ivar_type)
           return attr_skipped(ctx.path, class_name, method_name, :untyped_return)
         end
@@ -1377,6 +1901,15 @@ module Rigor
         end
       end
 
+      # ADR-112 WD4 — an attribute typed inline (`attr_reader :name #: String`) is written from that type, in
+      # the long `def` form the rest of the attr path uses.
+      def inline_attr_candidate(class_name, method_name, inline, ctx)
+        scope = ctx.scope_index.each_value.first
+        method_def = lookup_existing_method(class_name, method_name, :instance, scope&.environment, scope)
+        rbs = "def #{method_name}: #{inline.method_types.join(' | ')}"
+        inline_candidate(ctx.path, class_name, method_name, :instance, rbs, inline, method_def)
+      end
+
       def attr_new_candidate(path, class_name, method_name, variant, ivar_type)
         build_candidate(
           path: path,
@@ -1385,7 +1918,7 @@ module Rigor
           kind: :instance,
           classification: Classification::NEW_METHOD,
           inferred_return: ivar_type,
-          rbs: render_attr_rbs_line(method_name, variant, ivar_type)
+          rbs: render_attr_rbs_line(method_name, variant, ivar_type, class_name)
         )
       end
 
@@ -1402,7 +1935,7 @@ module Rigor
           path: path, class_name: class_name, method_name: method_name,
           kind: :instance, classification: Classification::TIGHTER_RETURN,
           inferred_return: ivar_type, declared_return_rbs: declared_rbs,
-          rbs: render_attr_rbs_line(method_name, variant, ivar_type)
+          rbs: render_attr_rbs_line(method_name, variant, ivar_type, class_name)
         )
       end
 
@@ -1426,8 +1959,8 @@ module Rigor
       # form can normalise post-emit; the writer-side member detection (slice 2) treats existing `attr_*`
       # declarations as user-authored so a paired source-side `attr_reader` never produces a duplicate `def`
       # insertion.
-      def render_attr_rbs_line(method_name, variant, ivar_type)
-        erased = elaborated_rbs(ivar_type)
+      def render_attr_rbs_line(method_name, variant, ivar_type, owner = nil)
+        erased = elaborated_rbs(ivar_type, owner: owner)
         wrapped = paren_wrap_union(erased)
         case variant
         when :reader then "def #{method_name}: () -> #{wrapped}"
@@ -1447,7 +1980,7 @@ module Rigor
           types = meta_member_types(class_name, layout.member_names)
           shape = MetaClassShape.of(
             kind: layout.kind, members: layout.member_names, keyword_init: layout.keyword_init,
-            member_types: types.transform_values { |type| paren_wrap_union(union_erase([type])) }
+            member_types: types.transform_values { |type| paren_wrap_union(union_erase([type], owner: class_name)) }
           )
           shape.member_decls.filter_map do |member|
             meta_member_candidate(path, class_name, member, types, scope, environment)