rigortype 0.3.8 → 0.4.0

data/lib/rigor/rbs_extended.rb

@@ -92,23 +92,87 @@ module Rigor
       end
     end
 
+    # The shared empty answers of the per-method readers. Dispatch consults the three readers on every RBS
+    # method it resolves (~150k each on the lib self-check) and nearly every method carries no `rigor:v1:`
+    # annotation, so a fresh `[]` / `{}` per decline was pure allocation. Callers never mutate a reader's
+    # result (`read_flow_contribution` selects into fresh arrays; the override map is documented read-only).
+    NO_DIRECTIVES = [].freeze
+    private_constant :NO_DIRECTIVES
+    NO_OVERRIDES = {}.freeze
+    private_constant :NO_OVERRIDES
+
+    # `%a{rigor:v1:inferred-return}` — the declaration states the member's presence and its parameters and
+    # says nothing about what it returns, so the return comes from the body. Normative in
+    # `docs/type-specification/rbs-extended.md`.
+    INFERRED_RETURN_DIRECTIVE = "rigor:v1:inferred-return"
+
+    # `%a{rigor:v1:inferred-signature}` — every type slot on the member, parameters and return alike,
+    # is a placeholder: the author's comment block asserted nothing about this member's own contract.
+    # Strictly narrower than {INFERRED_RETURN_DIRECTIVE}, which also covers a member with an authored
+    # parameter and no authored return. Normative in `docs/type-specification/rbs-extended.md`.
+    INFERRED_SIGNATURE_DIRECTIVE = "rigor:v1:inferred-signature"
+
     module_function
 
+    # Whether `method_def` declares its return type inferred rather than contracted (issue #823).
+    #
+    # The producer is `rigor-rbs-inline`: inside a file that carries one annotation, upstream rbs-inline
+    # emits a `(untyped, …) -> untyped` skeleton for every unannotated `def` too, and an accepted signature
+    # outranks body inference — so one annotation used to retype every sibling in its file to `untyped`.
+    # The plugin now marks exactly the type slots it DEFAULTED, and {MethodDispatcher::RbsDispatch} declines
+    # a marked member so the call takes the same body-inference tier an undeclared method takes. Nothing
+    # else about the declaration changes: the class keeps its full method surface, `new` keeps its arity,
+    # and cross-file references still resolve.
+    #
+    # Reads `RBS::Definition::Method#annotations`, so it answers for an inherited member too, and a
+    # hand-written `.rbs` may carry the annotation for the same effect.
+    #
+    # @param method_def — an `RBS::Definition::Method`, or anything else answering `#annotations`.
+    def inferred_return?(method_def)
+      return false if method_def.nil?
+
+      annotations = method_def.annotations
+      return false if annotations.nil? || annotations.empty?
+
+      annotations.any? { |annotation| annotation.string.to_s.strip == INFERRED_RETURN_DIRECTIVE }
+    end
+
+    # Whether `method_def` declares its ENTIRE signature inferred — every parameter and the return alike
+    # — rather than only its return (issue #991).
+    #
+    # `inferred_return?` alone cannot separate a fully bare `def` from one whose parameters ARE declared
+    # (`# @rbs num: Float`) and only its return defaulted: both trip the same return-only provenance,
+    # because no equivalent per-parameter survivor exists to tell them apart. This reads the plugin's
+    # narrower, member-level fact instead: true only when nothing at all was asserted about the member.
+    # `call.wrong-arity` declines on this rather than on {inferred_return?}, since a parameter the author
+    # DID annotate is an assertion about the parameter list, and the parameter list is exactly what arity
+    # is a question about (see the rule's own comment).
+    #
+    # @param method_def — an `RBS::Definition::Method`, or anything else answering `#annotations`.
+    def inferred_signature?(method_def)
+      return false if method_def.nil?
+
+      annotations = method_def.annotations
+      return false if annotations.nil? || annotations.empty?
+
+      annotations.any? { |annotation| annotation.string.to_s.strip == INFERRED_SIGNATURE_DIRECTIVE }
+    end
+
     # Reads RBS::Extended predicate effects off `RBS::Definition::Method#annotations`. Returns the effects in
     # source order; duplicates and unrecognised `rigor:v1:` directives are dropped. Returns an empty array (NEVER
     # `nil`) for a method with no recognised annotations so callers can iterate unconditionally.
     #
-    # @param environment [Rigor::Environment, nil] ADR-13 slice
+    # @param environment — ADR-13 slice
     #   3b. When provided, threads the plugin-supplied
     #   `name_scope:` and the per-run reporter through the
     #   annotation-parse path. `nil` (default) preserves the
     #   pre-slice-3b behaviour — no plugin resolvers consulted
     #   and no diagnostics accumulated.
     def read_predicate_effects(method_def, environment: nil)
-      return [] if method_def.nil?
+      return NO_DIRECTIVES if method_def.nil?
 
       annotations = method_def.annotations
-      return [] if annotations.nil? || annotations.empty?
+      return NO_DIRECTIVES if annotations.nil? || annotations.empty?
 
       name_scope = environment&.name_scope
       reporter = environment&.rbs_extended_reporter
@@ -127,10 +191,11 @@ module Rigor
     end
 
     # The right-hand side accepts either a Capitalised class name (with optional `~` negation, optional `::`
-    # prefix, qualified names) OR a kebab-case refinement payload routed through
-    # `Builtins::ImportedRefinements::Parser` (bare names, `name[T]`, `name<min, max>`). The two arms share the
-    # same overall directive shape; the parser detects which form matched by looking at the `class_name` vs
-    # `refinement` capture groups.
+    # prefix, qualified names) OR a refinement payload routed through
+    # `Builtins::ImportedRefinements::Parser` (bare kebab-case names, `name[T]`, the numeric range form
+    # `Integer[1..10]`, and the deprecated `name<min, max>`). The two arms share the same overall directive
+    # shape; the parser detects which form matched by looking at the `class_name` vs `refinement` capture
+    # groups. A class head followed by a bracketed range literal is a refinement (ADR-109), not a class name.
     PREDICATE_DIRECTIVE_PATTERN = /
       \A
       rigor:v1:(?<directive>predicate-if-(?:true|false))
@@ -141,7 +206,7 @@ module Rigor
       (?:
         (?<class_name>(?:::)?[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*)
         |
-        (?<refinement>[a-z][a-z0-9-]*(?:[\[<][^\]>]*[\]>])?)
+        (?<refinement>[a-z][a-z0-9-]*(?:[\[<][^\]>]*[\]>])?|[A-Z][A-Za-z0-9_]*\[[^\]]*\.\.[^\]]*\])
       )
       \s*
       \z
@@ -183,10 +248,10 @@ module Rigor
     #
     # See {.read_predicate_effects} for the `environment:` keyword contract.
     def read_assert_effects(method_def, environment: nil)
-      return [] if method_def.nil?
+      return NO_DIRECTIVES if method_def.nil?
 
       annotations = method_def.annotations
-      return [] if annotations.nil? || annotations.empty?
+      return NO_DIRECTIVES if annotations.nil? || annotations.empty?
 
       name_scope = environment&.name_scope
       reporter = environment&.rbs_extended_reporter
@@ -214,7 +279,7 @@ module Rigor
       (?:
         (?<class_name>(?:::)?[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*)
         |
-        (?<refinement>[a-z][a-z0-9-]*(?:[\[<][^\]>]*[\]>])?)
+        (?<refinement>[a-z][a-z0-9-]*(?:[\[<][^\]>]*[\]>])?|[A-Z][A-Za-z0-9_]*\[[^\]]*\.\.[^\]]*\])
       )
       \s*
       \z
@@ -352,7 +417,8 @@ module Rigor
 
     # The trailing payload supports the full refinement grammar in `Builtins::ImportedRefinements::Parser` — bare
     # kebab-case names plus parameterised forms like `non-empty-array[Integer]`, `non-empty-hash[Symbol,
-    # Integer]`, and `int<5, 10>`. The directive head is consumed by the regex; the rest is forwarded to the
+    # Integer]`, `Integer[5..10]`, and the deprecated `int<5, 10>`. The directive head is consumed by the regex;
+    # the rest is forwarded to the
     # refinement parser. Anything the parser cannot resolve falls back to nil so the call site keeps the
     # RBS-declared return type.
     RETURN_DIRECTIVE_PATTERN = /
@@ -449,7 +515,7 @@ module Rigor
 
     # Returned for `rigor:v1:param: <name> <refinement>`. The parameter name is a Ruby identifier (Symbol); the
     # type is any `Rigor::Type` the refinement parser resolves (bare kebab-case name, parameterised form, or
-    # `int<...>` range — the same grammar the `return:` directive accepts).
+    # `Integer[a..b]` range, or the deprecated `int<a, b>` — the same grammar the `return:` directive accepts).
     ParamOverride = Data.define(:param_name, :type)
 
     # Reads every `rigor:v1:param: <name> <refinement>` directive off `RBS::Definition::Method#annotations` and
@@ -469,10 +535,10 @@ module Rigor
     # argument-check purposes; passing a too-wide `Nominal[String]` argument is flagged as an argument-type
     # mismatch at the call site.
     def read_param_type_overrides(method_def, environment: nil)
-      return [] if method_def.nil?
+      return NO_DIRECTIVES if method_def.nil?
 
       annotations = method_def.annotations
-      return [] if annotations.nil? || annotations.empty?
+      return NO_DIRECTIVES if annotations.nil? || annotations.empty?
 
       name_scope = environment&.name_scope
       reporter = environment&.rbs_extended_reporter
@@ -491,9 +557,10 @@ module Rigor
     # frozen Hash<Symbol, Rigor::Type>; missing keys mean "use the RBS-declared type". Callers MUST treat the
     # hash as read-only.
     def param_type_override_map(method_def, environment: nil)
-      read_param_type_overrides(method_def, environment: environment)
-        .to_h { |o| [o.param_name, o.type] }
-        .freeze
+      overrides = read_param_type_overrides(method_def, environment: environment)
+      return NO_OVERRIDES if overrides.empty?
+
+      overrides.to_h { |o| [o.param_name, o.type] }.freeze
     end
 
     # The `is` glue word is optional so authors can write either `param: id is non-empty-string` (consistent with
@@ -708,9 +775,9 @@ module Rigor
     # `RBS::Extended` conflict channel) rather than silently resolved. Returns `nil` when the list
     # carries neither spelling.
     #
-    # @param annotations [Array<#string>] the node's annotations, in source order.
-    # @param owner_key [String] the method key (`Class#m` / `Class.m`) or class name the bound binds.
-    # @param source [Symbol] {Effects::Envelope::SOURCES} member to stamp when the labelled spelling
+    # @param annotations — the node's annotations, in source order.
+    # @param owner_key — the method key (`Class#m` / `Class.m`) or class name the bound binds.
+    # @param source — {Effects::Envelope::SOURCES} member to stamp when the labelled spelling
     #   matched; `%a{pure}` always stamps `:pure_annotation`, and a class-level read overrides both.
     def read_effect_envelope(annotations, owner_key:, source: :effect_annotation, registry: nil, reporter: nil)
       return nil if annotations.nil? || annotations.empty?

data/lib/rigor/reflection/constant_ancestors.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Rigor
+  # {Reflection}'s constant-ancestor walk ([#354](https://github.com/rigortype/rigor/issues/354)), split out for
+  # the reader rather than for the loader: the whole-spelling ladder's step 2 (`reflection.rb`) and the
+  # segment-wise path walk (`reflection/constant_path.rb`) both ask which project classes and modules a
+  # name's owner inherits constants from, and this file answers that once for both. Reopening the module
+  # keeps the walk behind the facade its callers already read.
+  module Reflection
+    # #354 — thread-local slot for the per-run ancestor-scope memo. See {.ancestor_constant_scopes}.
+    ANCESTOR_SCOPES_KEY = :__rigor_ancestor_constant_scopes__
+    private_constant :ANCESTOR_SCOPES_KEY
+
+    module_function
+
+    # #354 — the project classes and modules whose own constants `class_name` inherits, in Ruby's
+    # ancestor order: included / prepended modules before the superclass (Ruby places mixins nearer),
+    # transitively, breadth-first. `class_name` itself is excluded — step 1 already covered it.
+    #
+    # Only PROJECT ancestors appear. `Scope#superclass_of` / `#includes_of` carry as-written names
+    # from the discovery pre-pass, and an as-written name that resolves to no discovered class or
+    # module is dropped — so a `class Foo < ActiveRecord::Base` contributes nothing and a constant
+    # owned by an RBS-known ancestor still resolves only if the bare name reaches it at step 3. That
+    # gap is deliberate for this slice: widening to the RBS ancestor graph is a separate question
+    # with its own FP surface.
+    #
+    # Memoised per run because step 2 runs on every constant reference whose lexical candidates all
+    # miss — which is the common case for a core-class reference (`String` inside `class Foo`). The
+    # bucket keys on the identity of the runner-seeded run-generation token (ADR-84 WD2), falling
+    # back to the per-file discovery table for runner-less scopes, so a re-run in one process (LSP,
+    # ADR-62 warm loop) cannot hit stale entries.
+    def ancestor_constant_scopes(class_name, scope)
+      # ADR-46: `superclass_of` / `includes_of` record a cross-file class dependency per consumer
+      # file, and the memo is run-scoped rather than file-scoped — a hit would skip the recording and
+      # under-record the edge for every later file. Recording runs are rare (incremental only), so
+      # they simply bypass the memo rather than complicate its key.
+      return compute_ancestor_constant_scopes(class_name, scope) if Analysis::DependencyRecorder.active?
+
+      generation = scope.run_generation || scope.discovered_superclasses
+      slot = Thread.current[ANCESTOR_SCOPES_KEY]
+      unless slot && slot[0].equal?(generation)
+        slot = [generation, {}]
+        Thread.current[ANCESTOR_SCOPES_KEY] = slot
+      end
+      bucket = slot[1]
+      bucket.fetch(class_name) { bucket[class_name] = compute_ancestor_constant_scopes(class_name, scope) }
+    end
+    private_class_method :ancestor_constant_scopes
+
+    def compute_ancestor_constant_scopes(class_name, scope)
+      queue = [class_name]
+      seen = { class_name => true }
+      out = []
+      until queue.empty?
+        current = queue.shift
+        # Mixins first, then the superclass — Ruby's ancestor order.
+        scope.includes_of(current).each do |raw|
+          resolved = resolve_ancestor_name(current, raw, scope)
+          next if resolved.nil? || seen[resolved]
+
+          seen[resolved] = true
+          out << resolved
+          queue << resolved
+        end
+        raw_super = scope.superclass_of(current)
+        next if raw_super.nil?
+
+        resolved_super = resolve_ancestor_name(current, raw_super, scope)
+        next if resolved_super.nil? || seen[resolved_super]
+
+        seen[resolved_super] = true
+        out << resolved_super
+        queue << resolved_super
+      end
+      out.freeze
+    end
+    private_class_method :compute_ancestor_constant_scopes
+
+    # Resolves an ancestor name AS WRITTEN (`"Base"`, or a qualified `"A::B"`) against the nesting in
+    # force where the subclass's header is written — `Scope#ancestor_name_candidates`, the single
+    # owner of that order, which `Scope#enqueue_ancestors` reads for method lookup and the
+    # override-visibility rule reads for its own walk. Returns nil when no candidate names a
+    # discovered project class or module.
+    def resolve_ancestor_name(subclass_qualified, raw, scope)
+      scope.ancestor_name_candidates(subclass_qualified, raw)
+           .find { |candidate| known_project_namespace?(candidate, scope) }
+    end
+    private_class_method :resolve_ancestor_name
+
+    def known_project_namespace?(name, scope)
+      scope.discovered_superclasses.key?(name) ||
+        scope.discovered_includes.key?(name) ||
+        scope.discovered_classes.key?(name)
+    end
+    private_class_method :known_project_namespace?
+  end
+end

data/lib/rigor/reflection/constant_path.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Rigor
+  # {Reflection}'s second constant-resolution phase, split out for the reader rather than for the
+  # loader: `reflection.rb` asks what a whole spelling names under a series of prefixes, and this file
+  # asks what a PATH names segment by segment. Reopening the module rather than nesting under it keeps
+  # the walk inside the facade its callers already read, and lets it use the same private candidate
+  # lookups (`constant_type_at`, `enclosing_class_path`, `ancestor_constant_scopes`) the ladder uses.
+  module Reflection
+    module_function
+
+    # Issue #656 — Ruby's lookup for an as-written, unrooted constant PATH (`A::B`, `A::B::C`), which is
+    # a different question from "what does this whole string name under some prefix". Ruby resolves the
+    # FIRST segment through the ladder a bare name gets — `Module.nesting`, then the enclosing class's
+    # ancestors, then the top level — and then resolves each LATER segment inside the constant the
+    # previous segment produced, searching THAT constant's own ancestors in turn. So `A::B` written in
+    # `P::Guard` with `P::A < P::Base` names `P::Base::B`, while every whole-path candidate
+    # (`P::Guard::A::B`, `P::A::B`, `A::B`) either misses or names a real but different class.
+    #
+    # `known` decides the FINAL segment only, so the constant typer (any constant, values included) and
+    # `Inference::Narrowing`'s class-guard resolver (classes only) share one walk without sharing an
+    # acceptance test — the two cannot answer different names for the same spelling. Every earlier
+    # segment must name a namespace, because only a namespace can own the next one.
+    #
+    # Returns nil for a single-segment name — the callers' own ladders already own that case — and the
+    # moment any segment declines. Declining hands the caller back its unchanged fallback instead of a
+    # guess: a walk that finds the WRONG constant is worse than the wrong constant answered today
+    # (AGENTS.md § "Implementation Guidelines").
+    #
+    # Checked against MRI 4.0.5 rather than recollection: a later segment does NOT reach the top level
+    # for either a Class or a Module owner (`P::Mod::B` raises `NameError` where a top-level `B`
+    # exists), which is why {.constant_in_namespace} consults the owner's ancestors and stops. Rigor
+    # still lets its callers fall through to their own top-level rung there — that read raises at
+    # runtime and Rigor reports nothing about it either way, so retracting the resolution would trade a
+    # silent wrong answer for a silent absent one at no gain (the same reasoning as
+    # {.toplevel_first_constant_type}'s caller-derived rungs).
+    def resolve_constant_path_name(name, scope, &known)
+      walk_constant_path(name, scope, known, caller_derived: true)
+    end
+
+    # {.resolve_constant_path_name}'s walk. `caller_derived: false` is {.resolve_constant_type}'s flag: the
+    # head skips the enclosing class's ancestors — the one step a recorded top-level body takes from its
+    # caller — while every later segment still walks its owner's ancestors, as Ruby does.
+    def walk_constant_path(name, scope, known, caller_derived:)
+      segments = name.to_s.split("::")
+      return nil unless segments.size > 1
+
+      owner = path_head_owner(segments.first, scope, caller_derived)
+      last = segments.size - 1
+      segments.each_with_index do |segment, index|
+        next if index.zero?
+        return nil if owner.nil?
+
+        owner = constant_in_namespace(owner, segment, scope) do |candidate|
+          index == last ? known.call(candidate) : namespace_known?(candidate, scope)
+        end
+      end
+      owner
+    end
+    private_class_method :walk_constant_path
+
+    # Step 2.5's rung as a type: the segment-wise name, then that name looked up like any other
+    # candidate so the answer comes from the same source-precedence order as every other rung.
+    #
+    # Issue #1290 — the final segment's candidates are looked up with the reference's `shadows` names
+    # ({.constant_type_at}), so an owner's own `B` another file writes stops the walk before the owner's
+    # superclass answers with its published `B`.
+    def constant_path_type(name, scope, shadows:, caller_derived: true)
+      known = ->(candidate) { constant_type_at(candidate, scope, shadows) }
+      qualified = walk_constant_path(name, scope, known, caller_derived: caller_derived)
+      qualified && constant_type_at(qualified, scope, shadows)
+    end
+    private_class_method :constant_path_type
+
+    # The namespace a path's FIRST segment names — the bare-name ladder, restricted to answers that can
+    # OWN the segments that follow. A value constant is not one of them, so it declines here rather
+    # than producing a namespace prefix no source knows.
+    def path_head_owner(head, scope, caller_derived)
+      hit = first_namespace_hit(lexical_nesting_chain(scope), head, scope)
+      return hit if hit
+
+      prefix = caller_derived ? enclosing_class_path(scope) : nil
+      unless prefix.nil? || prefix.empty?
+        hit = first_namespace_hit(bounded_ancestor_scopes(prefix, scope), head, scope)
+        return hit if hit
+      end
+
+      head if namespace_known?(head, scope)
+    end
+    private_class_method :path_head_owner
+
+    # {.first_constant_hit}'s namespace twin: the first `<entry>::<name>` that can own further segments.
+    def first_namespace_hit(entries, name, scope)
+      entries.each do |entry|
+        candidate = "#{entry}::#{name}"
+        return candidate if namespace_known?(candidate, scope)
+      end
+      nil
+    end
+    private_class_method :first_namespace_hit
+
+    # `segment` looked up inside `owner` and then through `owner`'s own ancestors — Ruby's lookup for
+    # every segment after the first. `Object` is deliberately absent: MRI raises rather than reaching a
+    # top-level constant through an explicit `::` receiver.
+    def constant_in_namespace(owner, segment, scope)
+      candidate = "#{owner}::#{segment}"
+      return candidate if yield(candidate)
+
+      bounded_ancestor_scopes(owner, scope).each do |ancestor|
+        inherited = "#{ancestor}::#{segment}"
+        return inherited if yield(inherited)
+      end
+      nil
+    end
+    private_class_method :constant_in_namespace
+
+    # How many of {.ancestor_constant_scopes}' entries one segment may consult, under
+    # `Scope::ANCESTOR_WALK_LIMIT` — the budget `Scope`'s method lookup already spends on this same
+    # graph, reused rather than re-chosen so one pathological ancestry costs one bound. The list
+    # itself is the memoised one step 2 builds, so this bounds the per-segment consultation the walk
+    # adds and not the graph. Reported through the shared counter, so a truncated walk is visible in a
+    # budget trace instead of looking like a plain miss.
+    def bounded_ancestor_scopes(class_name, scope)
+      scopes = ancestor_constant_scopes(class_name, scope)
+      return scopes if scopes.size <= Scope::ANCESTOR_WALK_LIMIT
+
+      Inference::BudgetTrace.hit(Inference::BudgetTrace::ANCESTOR_WALK_LIMIT)
+      scopes.first(Scope::ANCESTOR_WALK_LIMIT)
+    end
+    private_class_method :bounded_ancestor_scopes
+
+    # Whether `name` can OWN a constant. `class_known?` covers the RBS and registry classes and modules;
+    # the project tables cover a namespace the project declares with no RBS for it.
+    def namespace_known?(name, scope)
+      scope.environment.class_known?(name) || known_project_namespace?(name, scope)
+    end
+    private_class_method :namespace_known?
+  end
+end