rigortype 0.4.1 → 0.4.3

data/lib/rigor/inference/string_mutation.rb

@@ -22,6 +22,9 @@ module Rigor
       # the effect classifier and the effect catalogue's `mutators: string` cite it rather than keep a list of their
       # own (ADR-103 WD3). A spec holds it to every bang method `String` defines plus the non-bang mutators reflection
       # cannot find by name.
+      #
+      # The last row is Ruby 4.1's bit operations (#1691), which `data/core_overlay/string.rbs` declares whatever Ruby
+      # runs the analysis; they rewrite bytes in place and keep the byte length.
       MUTATORS = %i[
         << concat insert prepend replace clear []= slice!
         setbyte bytesplice append_as_bytes force_encoding
@@ -29,18 +32,21 @@ module Rigor
         upcase! downcase! capitalize! swapcase! reverse!
         strip! lstrip! rstrip! chomp! chop!
         delete_prefix! delete_suffix! encode! scrub! unicode_normalize!
+        bit_set bit_clear bit_flip bitwise_not! bitwise_and! bitwise_or! bitwise_xor!
       ].to_set.freeze
 
       # The {MUTATORS} that CANNOT leave a non-empty receiver empty, and so keep a `non-empty-string` refinement:
       # appenders (`<<`, `concat`, `insert`, `prepend`, `append_as_bytes`), and rewrites that keep at least one
       # character (`setbyte`, `force_encoding`, the case mappings, `reverse!`, `succ!` / `next!`, `squeeze!`,
-      # `unicode_normalize!`). A whitelist, as `RefinementMutation::EMPTY_PRESERVING` is for Array and Hash: a mutator
-      # missing here retracts the witness, which costs precision, where a mutator missing from a list of emptiers kept
-      # the witness of a string it had just emptied — `tr!` and `tr_s!` did, since `"a".tr!("a", "")` is `""`.
+      # `unicode_normalize!`, and the bit operations, which keep every byte). A whitelist, as
+      # `RefinementMutation::EMPTY_PRESERVING` is for Array and Hash: a mutator missing here retracts the witness, which
+      # costs precision, where a mutator missing from a list of emptiers kept the witness of a string it had just
+      # emptied — `tr!` and `tr_s!` did, since `"a".tr!("a", "")` is `""`.
       EMPTY_PRESERVING = %i[
         << concat insert prepend append_as_bytes
         setbyte force_encoding
         upcase! downcase! capitalize! swapcase! reverse! succ! next! squeeze! unicode_normalize!
+        bit_set bit_clear bit_flip bitwise_not! bitwise_and! bitwise_or! bitwise_xor!
       ].to_set.freeze
 
       # `tr!` / `tr_s!` map every character they match to one character of the replacement (padded with its last), so

data/lib/rigor/inference/synthetic_method_scanner.rb

@@ -333,7 +333,8 @@ module Rigor
 
       def collect_included_do_calls(body)
         body.body.flat_map do |stmt|
-          next [] unless stmt.is_a?(Prism::CallNode) && stmt.receiver.nil? && stmt.name == :included && stmt.block
+          included_do = stmt.is_a?(Prism::CallNode) && stmt.receiver.nil? && stmt.name == :included
+          next [] unless included_do && stmt.block.is_a?(Prism::BlockNode)
 
           block_body = stmt.block.body
           next [] unless block_body.respond_to?(:body)

data/lib/rigor/inference/untyped_rejoin.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+require_relative "../source/node_walker"
+require_relative "captured_locals"
+
+module Rigor
+  module Inference
+    # Issue #1840 — a branch merge that re-joins the narrowed edges of an untyped local gives it back its
+    # untyped binding.
+    #
+    # Flow narrowing concretizes a `Dynamic[top]` receiver (ADR-83): `x.nil?` splits it into `nil` and
+    # `Dynamic[top]`, and `when String` into `String` and `Dynamic[top]`. `Scope#join` unions the edges, so
+    # after both merges the local reads `Dynamic[top] | String | nil`. That union is not wrong as a set, but
+    # every member is a narrowing of the one untyped value, so it says nothing the pre-branch binding did
+    # not. It does, however, hold `nil` beside a nameable class, and `call.possible-nil-receiver` reports
+    # `x + "a"` on correct code although neither narrowing alone did.
+    #
+    # The rule: at a merge, a local whose pre-branch binding is exactly `Dynamic[top]`, that no merged arm
+    # writes, and whose joined binding is a union still carrying a `Dynamic` member, is bound to
+    # `Dynamic[top]` again.
+    #
+    # - The write test keeps a nil the program puts there: `x = nil if c` writes `x`, so the join stays
+    #   `Dynamic[top] | nil` and still reports. It is syntactic, over every local-write form under the arms
+    #   (a pattern capture and a block's write to the outer local included), so a doubtful arm keeps today's
+    #   join. It does not see a written nil that a `nil?` edge stripped before the merge (`x = nil if c; if
+    #   x.nil? … elsif x.is_a?(String) … end`): that merge's entry is exactly `Dynamic[top]`, and the outer
+    #   join's `Dynamic[top] | nil` is one the possible-nil gate declines anyway (#1876).
+    # - The `Dynamic`-member test keeps a narrowing whose surviving arms no longer cover the untyped value:
+    #   `case x when String then … when Integer then … else raise end` leaves `Integer | String`, which is
+    #   what `x` is past it.
+    # - Only the `Dynamic[top]` facet: a faceted `Dynamic[T]` carries static knowledge of its own (a
+    #   plugin's or a signature's `T`), so a `nil` its narrowing leaves may be one the facet promised. Those
+    #   keep today's join.
+    #
+    # Restoring `Dynamic[top]` is always sound, since every narrowed edge is a subset of it; what it drops
+    # is only the nameable arms, which an untyped union never needed to dispatch.
+    module UntypedRejoin
+      module_function
+
+      # `joined` with each qualifying local rebound to its `entry` binding. `arms` are the nodes whose
+      # evaluation produced the merged scopes (`nil` entries are skipped).
+      def apply(joined, entry, arms)
+        candidates = nil
+        joined.locals.each do |name, type|
+          next unless candidate?(entry.locals[name], type)
+
+          (candidates ||= []) << name
+        end
+        return joined if candidates.nil?
+
+        written = written_locals(arms)
+        kept = candidates.reject { |name| written.include?(name) }
+        return joined if kept.empty?
+
+        joined.with_rejoined_locals(kept.to_h { |name| [name, entry.locals[name]] })
+      end
+
+      def candidate?(entry_type, joined_type)
+        entry_type.is_a?(Type::Dynamic) && entry_type.static_facet.is_a?(Type::Top) &&
+          joined_type.is_a?(Type::Union) && joined_type.members.any?(Type::Dynamic)
+      end
+
+      def written_locals(arms)
+        names = Set.new
+        arms.each do |arm|
+          Source::NodeWalker.each(arm) do |node|
+            names << node.name if CapturedLocals::LOCAL_WRITE_NODES.include?(node.class)
+          end
+        end
+        names
+      end
+    end
+  end
+end

data/lib/rigor/inference/version_guard.rb

@@ -33,6 +33,10 @@ module Rigor
     # Prism *parse* version (it decides which syntax is accepted), it is not threaded to the inference
     # layer, and its default (`"4.0"`) is a default rather than a user statement about the runtime.
     #
+    # The one exception is the Ruby-deprecation rule (the ADR-47 WD5 amendment, #1692). An explicit
+    # `target_ruby` is a user statement about the runtime, and that rule passes it as `stated_ruby:` to ask
+    # whether a deprecated call can run on the stated Ruby. Narrowing and the dead-arm filter never pass it.
+    #
     # ## What is folded (and what is deliberately not)
     #
     # * `RUBY_VERSION <cmp> "x.y.z"` — compared with **String** semantics, because that is what runs.
@@ -91,9 +95,13 @@ module Rigor
       private_constant :GEM_VERSION_PATH
 
       # @param node — an `if` / `unless` predicate
-      # @return `:truthy` / `:falsey` when the guard is decidable on the analyzer's Ruby,
+      # @param stated_ruby — ADR-47 WD5 amendment (#1692): a `x.y.z` version to read `RUBY_VERSION` as instead of
+      #   the analyzer's own, for the Ruby-deprecation rules only ({Configuration#stated_runtime_ruby}). Under it
+      #   nothing else is readable — `RUBY_ENGINE` and the default gems' `VERSION`s belong to the analyzer's
+      #   interpreter, not to the stated one — so a guard on them answers nil.
+      # @return `:truthy` / `:falsey` when the guard is decidable on the analyzer's Ruby (or on `stated_ruby`),
       #   otherwise nil (both arms stay live)
-      def verdict(node)
+      def verdict(node, stated_ruby: nil)
         return nil unless node.is_a?(Prism::CallNode)
 
         operator = node.name
@@ -103,19 +111,19 @@ module Rigor
         arguments = node.arguments&.arguments
         return nil unless arguments && arguments.length == 1
 
-        left = read_operand(node.receiver)
-        right = read_operand(arguments.first)
+        left = read_operand(node.receiver, stated_ruby)
+        right = read_operand(arguments.first, stated_ruby)
         return nil if left.nil? || right.nil?
 
         decide(left, right, operator)
       end
 
       # Reads one side of the comparison into `[kind, value]`, or nil when it is not readable.
-      def read_operand(node)
+      def read_operand(node, stated_ruby = nil)
         case node
         when Prism::StringNode then [:literal_string, node.unescaped]
-        when Prism::ConstantReadNode, Prism::ConstantPathNode then read_constant(node)
-        when Prism::CallNode then read_gem_version(node)
+        when Prism::ConstantReadNode, Prism::ConstantPathNode then read_constant(node, stated_ruby)
+        when Prism::CallNode then read_gem_version(node, stated_ruby)
         end
       end
       private_class_method :read_operand
@@ -129,9 +137,10 @@ module Rigor
       #
       # The foldable set is unchanged and stays closed: an unqualified name folds only when it is one of
       # {PREDEFINED}, a qualified one only when it is in {VERSION_CONSTANTS}.
-      def read_constant(node)
+      def read_constant(node, stated_ruby = nil)
         path = Source::ConstantPath.qualified_name_or_nil(node)
         return nil unless path
+        return (path == "RUBY_VERSION" ? [:string, stated_ruby] : nil) if stated_ruby
 
         kind =
           if path.include?("::")
@@ -149,14 +158,14 @@ module Rigor
       # `Gem::Version.new(<readable>)`. The inner operand must be a plain version String — an engine name
       # is not a version, and `Gem::Version.new` raises on anything `Gem::Version.correct?` rejects, so a
       # malformed literal keeps both arms live instead of folding a guard the program cannot even reach.
-      def read_gem_version(node)
+      def read_gem_version(node, stated_ruby = nil)
         return nil unless node.name == :new && node.block.nil?
         return nil unless Source::ConstantPath.qualified_name_or_nil(node.receiver) == GEM_VERSION_PATH
 
         arguments = node.arguments&.arguments
         return nil unless arguments && arguments.length == 1
 
-        inner = read_operand(arguments.first)
+        inner = read_operand(arguments.first, stated_ruby)
         return nil unless inner && STRING_KINDS.include?(inner.first)
         return nil unless ::Gem::Version.correct?(inner.last)
 

data/lib/rigor/language_server/project_context.rb

@@ -6,6 +6,7 @@ require_relative "../cache/store"
 require_relative "../analysis/runner"
 require_relative "../analysis/incremental_session"
 require_relative "../cache/incremental_snapshot"
+require_relative "../effects/identity"
 
 module Rigor
   module LanguageServer
@@ -24,6 +25,10 @@ module Rigor
     # are small (the per-publish path is already ≈2ms once Environment is warm).
     #
     # Invalidation:
+    # - Every whole-project round (`#project_diagnostics`) re-reads the configuration and compares the
+    #   incremental snapshot fingerprint and the `effects:` identity with the ones its session was primed with,
+    #   re-baselining on any change — so no file watcher or `didChangeConfiguration` is needed for
+    #   `.rigor.yml`, `sig/`, `pre_eval:` or lockfile edits (#1613).
     # - `#invalidate!` drops the cached environment AND project scan + bumps the generation counter; the next
     #   reader rebuilds. Watched-file changes (`workspace/didChangeWatchedFiles`) and configuration refreshes
     #   (`workspace/didChangeConfiguration`) both trigger this — the next publish observes the new project
@@ -44,8 +49,16 @@ module Rigor
       # invalidated never reach the editor.
       attr_reader :configuration, :generation
 
-      def initialize(configuration:)
+      # `configuration_loader` re-reads the configuration (e.g. `-> { Configuration.load(path) }`); a save round
+      # calls it so an edit to `.rigor.yml` (or a file it `includes:`) reaches the server without a restart. Nil
+      # keeps the configuration the context was built with.
+      def initialize(configuration:, configuration_loader: nil)
         @configuration = configuration
+        @configuration_loader = configuration_loader
+        @primed_key = nil
+        @buffer_sources = {}
+        @disk_feature_files = nil
+        @environment_features = nil
         @generation = 0
         @environment = nil
         @cache_store = nil
@@ -77,6 +90,9 @@ module Rigor
           dependency_source_index: project_scan.dependency_source_index,
           synthetic_method_index: project_scan.synthetic_method_index,
           project_patched_methods: project_scan.project_patched_methods,
+          # Issue #1700 — the configured paths' files overlaid with the open buffers; {#note_buffers}
+          # rebuilds this when an edit or a save changes the set.
+          required_features: (@environment_features = required_features),
           **ProjectEnvironment.dependency_discovery_options(@configuration)
         )
       end
@@ -104,38 +120,104 @@ module Rigor
       # The session is never persisted. Its state lives as long as this context, which is what a long-running
       # server needs, and writing it would race exactly the way the read-only {#cache_store} exists to avoid.
       # Seeding is therefore one-directional: the terminal warms the server, not the reverse.
+      #
+      # Every round recomputes {Cache::IncrementalSnapshot.fingerprint} (the function the CLI's `--incremental`
+      # keys its snapshot on — one input list) and compares it with the one the session was primed with. A
+      # session's recheck only sees source-file digests, so an edit to a `pre_eval:` file, an auto-detected
+      # `sig/*.rbs`, a lockfile or `.rigor.yml` would otherwise keep serving answers computed from the old
+      # inputs until the server restarts (#1613). A change — including a fingerprint that newly cannot be
+      # computed — drops the session and the world built from the old inputs and re-baselines, so the round equals
+      # a cold run. The `effects:` identity rides along because `Configuration#to_h` omits `effects:`, so the
+      # fingerprint alone does not move on an `effects:` edit. A fingerprint that was ALREADY uncomputable at
+      # priming is not a change: that session keeps rechecking.
+      # {#generation} is deliberately NOT bumped: the round that notices the change is itself computed from the
+      # new inputs, and the publisher discards a round whose generation moved.
       def project_diagnostics
+        reload_configuration
+        fingerprint = current_fingerprint
+        key = [fingerprint, Effects::Identity.digest(configuration: @configuration)]
+        rebaseline if @session_primed && key != @primed_key
         session = (@incremental_session ||= build_incremental_session)
         return session.recheck.diagnostics if @session_primed
 
         @session_primed = true
+        @primed_key = key
         diagnostics, = session.run_incremental(
           snapshot: Cache::IncrementalSnapshot.new(root: @configuration.cache_path),
-          fingerprint: Cache::IncrementalSnapshot.fingerprint(
-            configuration: @configuration, roots: @configuration.paths
-          ),
+          fingerprint: fingerprint,
           persist: false
         )
         diagnostics
       end
 
+      # Issue #1700 — records the open buffers' text (absolute path => source) and rebuilds the environment
+      # when it changes the {Environment::RequiredFeatures} set the current one was built with: a buffer that
+      # gains or drops a `require "prime"` loads or unloads the vendored `prime` signatures. The server calls
+      # it on every open, change, save and close; neither `didSave` nor a `.rb` edit reaches
+      # `workspace/didChangeWatchedFiles`, which most clients send only for the files they were asked to watch.
+      # The configured paths are read once per environment and only the buffers are re-scanned, so a keystroke
+      # costs a substring test per open buffer.
+      def note_buffers(sources)
+        @buffer_sources = sources
+        return if @environment.nil? || required_features == @environment_features
+
+        invalidate!
+      end
+
+      # The required-feature set for the configured paths' files on disk, each open buffer read in place of its
+      # file.
+      def required_features
+        disk = (@disk_feature_files ||= Environment::RequiredFeatures.feature_files(@configuration))
+        found = disk.reject { |path, _| @buffer_sources.key?(path) }.values.flatten
+        found += @buffer_sources.values.flat_map { |source| Environment::RequiredFeatures.features_of(source) }
+        found.uniq.sort.freeze
+      end
+
       # Drops every cached collaborator and bumps the generation. The next reader rebuilds from scratch.
       # Triggered by `workspace/didChangeWatchedFiles` for project source files and by
       # `workspace/didChangeConfiguration`.
       def invalidate!
         @generation += 1
+        reset_world
+      end
+
+      private
+
+      # Drops what was built from the previous inputs, without touching {#generation}.
+      def reset_world
         @environment = nil
+        @environment_features = nil
+        @disk_feature_files = nil
         @project_scan = nil
         # The session's per-file cache was computed against the old environment / project scan, so it cannot
         # outlive them. The next save round primes a fresh one.
         @incremental_session = nil
         @session_primed = false
+        @primed_key = nil
         # Cache store stays — it's content-addressed; a stale env build won't be served because the file
         # digest mixed into the cache key has changed.
         nil
       end
 
-      private
+      # A changed configuration may also move `cache_path`, so the store goes too (unlike {#invalidate!}).
+      def rebaseline
+        reset_world
+        @cache_store = nil
+      end
+
+      def current_fingerprint
+        Cache::IncrementalSnapshot.fingerprint(configuration: @configuration, roots: @configuration.paths)
+      end
+
+      # A load that raises (a half-typed `.rigor.yml`) keeps the previous configuration: the editor must not
+      # lose its diagnostics to a transient parse error, and the next round retries.
+      def reload_configuration
+        return unless @configuration_loader
+
+        @configuration = @configuration_loader.call
+      rescue StandardError
+        nil
+      end
 
       # The session shares this context's warm Environment, so a round does not rebuild the RBS universe. It
       # deliberately does NOT share the prebuilt ProjectScan: a round runs after a save, i.e. after the file

data/lib/rigor/language_server/server.rb

@@ -2,6 +2,7 @@
 
 require_relative "../version"
 require_relative "buffer_table"
+require_relative "uri"
 
 module Rigor
   module LanguageServer
@@ -221,6 +222,7 @@ module Rigor
           bytes: doc.fetch(:text),
           version: doc.fetch(:version)
         )
+        note_buffers
         @publisher&.publish_for(uri)
         nil
       end
@@ -242,6 +244,7 @@ module Rigor
           changes: changes,
           version: doc.fetch(:version)
         )
+        note_buffers
         @publisher&.publish_for(uri)
         nil
       end
@@ -257,6 +260,7 @@ module Rigor
       def handle_did_save(params)
         uri = params.fetch(:textDocument).fetch(:uri)
         @buffer_table.save(uri: uri)
+        note_buffers
         @publisher&.publish_project(uri)
         nil
       end
@@ -361,10 +365,24 @@ module Rigor
         doc = params.fetch(:textDocument)
         uri = doc.fetch(:uri)
         @buffer_table.close(uri: uri)
+        note_buffers
         @publisher&.publish_empty(uri)
         nil
       end
 
+      # Issue #1700 — hands the open Ruby buffers to the project context, which rebuilds its environment when
+      # they change the set of required features the vendored signatures are gated on.
+      def note_buffers
+        return unless @project_context.respond_to?(:note_buffers)
+
+        sources = @buffer_table.uris.each_with_object({}) do |uri, acc|
+          path = Uri.to_path(uri)
+          entry = @buffer_table[uri]
+          acc[File.expand_path(path)] = entry.bytes if path&.end_with?(".rb") && entry
+        end
+        @project_context.note_buffers(sources)
+      end
+
       def method_not_found(method)
         rpc_error(ERROR_METHOD_NOT_FOUND, "method not found: #{method.inspect}")
       end

data/lib/rigor/lens/anchor.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative "../hashing/xxh3"
+
+module Rigor
+  module Lens
+    # A site's anchor and contract-comment span (docs/internal-spec/lens.md § Anchors). The hashed material is the
+    # contract comment lines above the declaration (`#:`, `@rbs`, `@extrbs` and their continuation lines), the
+    # declaration's own bytes, and a `#:` comment trailing its last line. Documentation prose is not part of it.
+    class Anchor
+      Result = Data.define(:token, :line, :contract_comments)
+
+      # rbs-inline's annotation grammar (`#:`, `#[`, `#\s*@rbs`) plus `@extrbs`, matched from the `#`.
+      CONTRACT_COMMENT = /\A#(?::|\[|\s*@rbs\b|\s*@extrbs\b)/
+      # A `#:nodoc:`-style RDoc directive, which the rbs-inline plugin neutralises rather than reads.
+      RDOC_DIRECTIVE = /\A#:[a-z_][\w-]*:/
+      # A kept line that later comment lines may continue, with the spaces between its `#` and the tag.
+      CONTINUED_TAG = /\A#( *)@(?:rbs|extrbs)\b/
+
+      # @param source — the file's bytes (binary String)
+      # @param comments — the file's `Prism::Comment` list
+      def initialize(source, comments)
+        @source = source.b
+        @line_starts = [0]
+        @source.each_byte.with_index { |byte, index| @line_starts << (index + 1) if byte == 10 }
+        @comment_by_line = {}
+        comments.each do |comment|
+          next unless comment.is_a?(Prism::InlineComment)
+
+          @comment_by_line[comment.location.start_line] = comment
+        end
+      end
+
+      # The anchor of the declaration spanning bytes `start_offset...end_offset` and lines `start_line..end_line`.
+      def for_span(start_offset, end_offset, start_line, end_line)
+        leading = leading_contract_comments(start_line)
+        trailing = trailing_contract_comment(end_line, end_offset)
+        material = +"".b
+        leading.each { |comment| material << line_text_from(comment.location.start_offset) << "\n" }
+        material << @source.byteslice(start_offset, end_offset - start_offset)
+        material << "\n" << line_text_from(trailing.location.start_offset) if trailing
+        line = leading.empty? ? start_line : leading.first.location.start_line
+        Result.new(token: "#{line}:#{Hashing::XXH3.anchor_hash(material)}", line: line,
+                   contract_comments: leading + [trailing].compact)
+      end
+
+      private
+
+      # The contract comments among the contiguous comment-only lines directly above `start_line`, in file order,
+      # with rbs-inline's continuation lines below a kept `@rbs` / `@extrbs` line.
+      def leading_contract_comments(start_line)
+        run = []
+        line = start_line - 1
+        while line >= 1 && (comment = comment_only_line(line))
+          run.unshift(comment)
+          line -= 1
+        end
+        kept = []
+        tag_indent = nil
+        run.each do |comment|
+          text = comment_text(comment)
+          if tag_indent && hash_indent(text) > tag_indent
+            kept << comment
+            next
+          end
+
+          tag_indent = nil
+          next unless contract_comment?(text)
+
+          kept << comment
+          continued = text.match(CONTINUED_TAG)
+          tag_indent = continued && continued[1].size
+        end
+        kept
+      end
+
+      def trailing_contract_comment(end_line, end_offset)
+        comment = @comment_by_line[end_line]
+        return nil if comment.nil? || comment.location.start_offset < end_offset
+
+        text = comment_text(comment)
+        contract_comment?(text) && text.start_with?("#:") ? comment : nil
+      end
+
+      def contract_comment?(text)
+        text.match?(CONTRACT_COMMENT) && !text.match?(RDOC_DIRECTIVE)
+      end
+
+      # The spaces between a comment's `#` and its first non-space byte.
+      def hash_indent(text)
+        text[/\A#( *)/, 1].size
+      end
+
+      # The comment on `line` when nothing but whitespace precedes it.
+      def comment_only_line(line)
+        comment = @comment_by_line[line]
+        return nil if comment.nil?
+
+        prefix = @source.byteslice(@line_starts[line - 1], comment.location.start_offset - @line_starts[line - 1])
+        prefix.match?(/\A[ \t]*\z/) ? comment : nil
+      end
+
+      # The comment's text from its `#`, without a line terminator.
+      def comment_text(comment)
+        comment.location.slice.b.chomp.delete_suffix("\r")
+      end
+
+      # The bytes from `offset` to the end of its line, without the line terminator.
+      def line_text_from(offset)
+        line_end = @source.index("\n", offset) || @source.bytesize
+        @source.byteslice(offset, line_end - offset).delete_suffix("\r")
+      end
+    end
+  end
+end

data/lib/rigor/lens/contract_reader.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require_relative "slot"
+require_relative "../reflection"
+
+module Rigor
+  module Lens
+    # Reads a member's own RBS declaration into overloads with per-slot provenance (docs/internal-spec/lens.md
+    # § Members). A declaration the member inherits is not its contract; one written for its own class is, whether
+    # it comes from `sig/`, an inline comment, a plugin or a library.
+    class ContractReader
+      INFERRED_RETURN = "rigor:v1:inferred-return"
+      INFERRED_SIGNATURE = "rigor:v1:inferred-signature"
+
+      # `overloads` hold `{rbs, params, block, return}`; a return the contract leaves to inference is nil there,
+      # with `return_inferred` set. `buffers` are the declaring buffer names.
+      Contract = Data.define(:overloads, :provenance, :path, :return_inferred, :buffers)
+
+      def initialize(provenance)
+        @provenance = provenance
+      end
+
+      # The member's contract, or nil when it has none of its own. `name` is the Ruby method name.
+      def read(owner, scope, name, lookup_scope)
+        method = lookup(owner, scope, name, lookup_scope)
+        defs = method ? method.defs.select { |definition| definition.defined_in.to_s.delete_prefix("::") == owner } : []
+        return nil if defs.empty?
+
+        annotations = annotations_of(method, defs)
+        return nil if annotations.include?(INFERRED_SIGNATURE)
+
+        contract(defs, annotations)
+      rescue StandardError
+        unreadable("definition_build_failed", [])
+      end
+
+      private
+
+      def contract(defs, annotations)
+        buffers = defs.map { |definition| buffer_name(definition) }
+        classified = buffers.map { |buffer| @provenance.classify(buffer) }
+        return unreadable("not_computed", buffers) if classified.include?(nil)
+
+        return_inferred = annotations.include?(INFERRED_RETURN)
+        authored = annotations.select do |string|
+          string.start_with?("rigor:v1:") && !string.start_with?(INFERRED_RETURN)
+        end
+        # Each overload carries the provenance of the declaration it came from: a `sig/` overload extending a
+        # library declaration reads `sig`, the library one `library`.
+        overloads = defs.zip(classified).map do |definition, (provenance, path)|
+          overload(definition.type, provenance, path, return_inferred, authored)
+        end
+        provenance, path = classified.first
+        Contract.new(overloads: overloads, provenance: provenance, path: path,
+                     return_inferred: return_inferred, buffers: buffers)
+      end
+
+      # The method's and its own declarations' annotation strings: the plugin's defaulted-slot marks and authored
+      # `%a{…}`.
+      def annotations_of(method, defs)
+        strings = method.annotations.map(&:string) + defs.flat_map { |definition| definition.annotations.map(&:string) }
+        strings.map(&:strip).uniq
+      end
+
+      def buffer_name(definition)
+        location = definition.member&.location
+        location ? location.buffer&.name.to_s : ""
+      end
+
+      def lookup(owner, scope, name, lookup_scope)
+        if scope == :singleton
+          Reflection.singleton_method_definition(owner, name.to_sym, scope: lookup_scope)
+        else
+          Reflection.instance_method_definition(owner, name.to_sym, scope: lookup_scope)
+        end
+      end
+
+      # A declaration Rigor cannot read: its buffer name did not survive the environment cache
+      # (`not_computed`), or building the member's definition failed (`definition_build_failed`). The member has a
+      # contract, so it is not inferred; every slot is unavailable, and so are its parameters (`params: null`).
+      def unreadable(reason, buffers)
+        Contract.new(overloads: [{ "rbs" => nil, "params" => nil, "block" => nil,
+                                   "return" => Slot.unavailable(reason) }],
+                     provenance: nil, path: nil, return_inferred: false, buffers: buffers)
+      end
+
+      def overload(method_type, provenance, path, return_inferred, annotations)
+        function = method_type.type
+        params = function.respond_to?(:required_positionals) ? params_of(function, provenance, path) : nil
+        block = method_type.block && { "required" => method_type.block.required,
+                                       "type" => Slot.from_rbs(method_type.block.type.to_s, provenance, path) }
+        prefix = annotations.map { |string| "%a{#{string}} " }.join
+        return_slot = return_inferred ? nil : Slot.from_rbs(function.return_type.to_s, provenance, path)
+        { "rbs" => "#{prefix}#{method_type}", "params" => params, "block" => block, "return" => return_slot,
+          "return_rbs" => function.return_type.to_s }
+      end
+
+      def params_of(function, provenance, path)
+        (positional_params(function) + keyword_params(function)).map do |kind, name, param|
+          { "name" => name&.to_s, "kind" => kind, "type" => Slot.from_rbs(param.type.to_s, provenance, path) }
+        end
+      end
+
+      def positional_params(function)
+        function.required_positionals.map { |param| ["required", param.name, param] } +
+          function.optional_positionals.map { |param| ["optional", param.name, param] } +
+          [function.rest_positionals].compact.map { |param| ["rest", param.name, param] } +
+          function.trailing_positionals.map { |param| ["post", param.name, param] }
+      end
+
+      def keyword_params(function)
+        function.required_keywords.map { |name, param| ["keyreq", name, param] } +
+          function.optional_keywords.map { |name, param| ["key", name, param] } +
+          [function.rest_keywords].compact.map { |param| ["keyrest", param.name, param] }
+      end
+    end
+  end
+end