rigortype 0.4.7 → 0.4.8

data/lib/rigor/lens/claims.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require_relative "claims/request"
+require_relative "claims/type_reader"
+require_relative "claims/comparison"
+
+module Rigor
+  module Lens
+    # Read-only documentation coverage against the contracts retained by this lens run.
+    class Claims
+      REASONS = %w[no_such_declaration unsupported_declaration declaration_mismatch unsupported_subject
+                   no_authored_contract unsupported_contract_source extrbs_contract refined_contract
+                   unsupported_overloads no_such_parameter unsupported_parameter_kind unmatched_parameter
+                   unsupported_grammar_feature unresolved_name ambiguous_name dynamic_type unsupported_type
+                   unproven].freeze
+      POSITIONALS = %w[required optional rest post].freeze
+
+      def initialize(request:, outcome:, run:)
+        @request = request
+        @outcome = outcome
+        @run = run
+      end
+
+      def call
+        @request.verify_sources!(@outcome.targets)
+        { "schema" => "lens-claims/v0", "revision" => 1, "request_digest" => @request.digest,
+          "grammar" => "rbs", "capabilities" => %w[return required_param required_keyword],
+          "results" => @request.claims.map { |claim| result(claim) } }
+      end
+
+      private
+
+      def result(claim)
+        answer = { "id" => claim.fetch("id"), "verdict" => "unknown", "reason" => "unproven",
+                   "relation" => nil, "direction" => nil, "site" => nil, "member" => nil,
+                   "slot" => nil, "contract" => nil, "evidence" => [] }
+        target = @outcome.targets.find { |entry| entry.absolute == @request.paths.fetch(claim.fetch("file")) }
+        return answer.merge("verdict" => "unavailable", "reason" => target.status) unless target.status == "ok"
+
+        parsed, grammar_reason = TypeReader.parse(claim.fetch("claim"))
+        if grammar_reason == "syntax_error"
+          return answer.merge("verdict" => "invalid_claim",
+                              "reason" => "syntax_error")
+        end
+
+        site, member, reason = bind(claim.fetch("declaration"), target.reader)
+        return answer.merge("reason" => reason) if reason
+
+        answer.merge!("site" => site.data.fetch("key"), "member" => member.slice("owner", "scope", "name"))
+        check_slot(claim, parsed, grammar_reason, site, member, target, answer)
+      end
+
+      def bind(declaration, reader)
+        sites = reader.sites.select { |site| same_span?(site.data.fetch("span"), declaration.fetch("span")) }
+        if sites.empty?
+          omission = reader.omissions.any? { |entry| same_span?(entry.fetch("span"), declaration.fetch("span")) }
+          return [nil, nil, omission ? "unsupported_declaration" : "no_such_declaration"]
+        end
+        return [nil, nil, "unsupported_declaration"] unless sites.one? && sites.first.data["kind"] == "method"
+
+        site = sites.first
+        member = @outcome.member_rows.find do |row|
+          row.values_at("owner", "scope", "name") == declaration.values_at("owner", "scope", "name") &&
+            row.fetch("sites").include?(site.data.fetch("key")) && declaration["kind"] == "method"
+        end
+        member ? [site, member, nil] : [nil, nil, "declaration_mismatch"]
+      end
+
+      def same_span?(left, right)
+        left.values_at("start_offset", "end_offset") == right.values_at("start_offset", "end_offset")
+      end
+
+      def check_slot(claim, parsed, grammar_reason, site, member, target, answer)
+        tag = claim.fetch("tag")
+        return answer.merge("reason" => "unsupported_subject") unless supported_subject?(tag)
+
+        raw = @run.raw_contracts[member.values_at("owner", "scope", "name")]
+        overloads = member.fetch("overloads")
+        reasons = member_reasons(site, member) + [grammar_reason].compact
+        slot, index, subject_reason = subject(tag, site, overloads.one? ? overloads.first : nil)
+        reasons << subject_reason if subject_reason
+        if slot
+          read_slot(slot, index, tag, overloads.first, raw, answer, reasons)
+          type = authored_type(raw, tag, index)
+          compare_types(parsed, type, site, target, answer, reasons) if parsed && type
+        end
+        reason = REASONS.find { |candidate| reasons.include?(candidate) }
+        reason ? answer.merge("verdict" => "unknown", "reason" => reason, "evidence" => []) : answer
+      end
+
+      def supported_subject?(tag)
+        %w[param return].include?(tag.fetch("name")) && (tag["name"] == "return" || tag["subject"])
+      end
+
+      def authored_type(raw, tag, index)
+        contract_type(raw.types.first.type, tag, index) if raw&.types&.one?
+      end
+
+      def member_reasons(site, member)
+        reasons = []
+        overloads = member.fetch("overloads")
+        reasons << "no_authored_contract" if member["basis"] != "contract"
+        reasons << "unsupported_overloads" unless overloads.one? && overloads.first["params"]
+        reasons << "extrbs_contract" if site.contract_comments.any? do |comment|
+          comment.location.slice.match?(/\A#\s*@extrbs\b/)
+        end
+        reasons
+      end
+
+      def read_slot(slot, index, tag, overload, raw, answer, reasons)
+        answer.merge!("relation" => "documentation_coverage", "slot" => slot,
+                      "direction" => tag["name"] == "param" ? "claim_within_contract" : "contract_within_claim")
+        contract = tag["name"] == "return" ? overload["return"] : overload.fetch("params")[index]["type"]
+        inspect_contract(contract, raw, tag, index, answer, reasons)
+      end
+
+      def inspect_contract(contract, raw, tag, index, answer, reasons)
+        if contract.nil? || contract["state"] == "unavailable" || contract["provenance"] == "inferred"
+          reasons << "no_authored_contract"
+          return
+        end
+        provenance = contract["provenance"]
+        reasons << "unsupported_contract_source" if provenance == "library" || provenance&.start_with?("plugin:")
+        answer["contract"] = contract.slice("type", "provenance", "path")
+        reasons << "refined_contract" if refined?(raw, tag, index)
+      end
+
+      def refined?(raw, tag, index)
+        return false if raw.nil?
+        return raw.annotations.any? { |text| text.start_with?("rigor:v1:return:") } if tag["name"] == "return"
+
+        raw.types.any? do |method_type|
+          function = method_type.type
+          param = function_params(function)[index]
+          if function.respond_to?(:required_keywords)
+            keyword = function.required_keywords.find do |_key, value|
+              value.equal?(param)
+            end
+          end
+          name = keyword ? keyword.first : param&.name
+          name && raw.annotations.any? { |text| text.match?(/\Arigor:v1:param:\s*#{Regexp.escape(name.to_s)}\s/) }
+        end
+      end
+
+      def subject(tag, site, overload)
+        return [{ "kind" => "return" }, nil, nil] if tag["name"] == "return" && overload
+        return [nil, nil, nil] if tag["name"] == "return"
+
+        params = site.data["params"] || []
+        param = params.find { |entry| entry["name"] == tag["subject"] }
+        return [nil, nil, "no_such_parameter"] unless param
+        return [nil, nil, "unsupported_parameter_kind"] unless %w[required keyreq].include?(param["kind"])
+        return [nil, nil, nil] unless overload && overload["params"]
+
+        declared = overload.fetch("params")
+        index = parameter_index(param, params, declared)
+        return [nil, nil, "unmatched_parameter"] unless index
+
+        [{ "kind" => "param", "name" => param["name"], "param_kind" => param["kind"], "index" => index }, index, nil]
+      end
+
+      def parameter_index(param, params, declared)
+        if param["kind"] == "keyreq"
+          return declared.index { |entry| entry["kind"] == "keyreq" && entry["name"] == param["name"] }
+        end
+
+        source_positions = params.select { |entry| POSITIONALS.include?(entry["kind"]) }
+        contract_positions = declared.select { |entry| POSITIONALS.include?(entry["kind"]) }
+        return unless source_positions.map { |entry| entry["kind"] } == contract_positions.map { |entry| entry["kind"] }
+
+        source_positions.index(param)
+      end
+
+      def contract_type(function, tag, index)
+        tag["name"] == "return" ? function.return_type : function_params(function)[index]&.type
+      end
+
+      def function_params(function)
+        return [] unless function.respond_to?(:required_positionals)
+
+        function.required_positionals + function.optional_positionals + [function.rest_positionals].compact +
+          function.trailing_positionals + function.required_keywords.values + function.optional_keywords.values +
+          [function.rest_keywords].compact
+      end
+
+      def compare_types(parsed, contract, site, target, answer, reasons)
+        scope = @run.claim_contexts.fetch(target.absolute)
+        nesting = site.data.fetch("lexical_nesting")
+        reader = TypeReader.new(scope: scope, nesting: nesting, singleton_nesting: site.data["singleton_nesting"],
+                                owner: site.data["owner"])
+        claim_arms = reader.read(parsed, claim: true)
+        contract_arms = reader.read(contract)
+        reasons.concat(reader.reasons.to_a)
+        return unless reasons.empty?
+
+        left, right = if answer["direction"] == "claim_within_contract"
+                        [claim_arms, contract_arms]
+                      else
+                        [contract_arms, claim_arms]
+                      end
+        comparator = Comparison.new(scope.environment.rbs_loader,
+                                    relative_conflict: nesting == [] && site.data["owner"] == "Object")
+        verdict, reason, evidence = comparator.call(left, right)
+        answer.merge!("verdict" => verdict, "reason" => reason, "evidence" => evidence)
+      end
+    end
+  end
+end

data/lib/rigor/lens/contract_reader.rb

@@ -16,9 +16,13 @@ module Rigor
       # `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)
+      RawContract = Data.define(:types, :annotations)
+
+      attr_reader :raw_contracts
 
       def initialize(provenance)
         @provenance = provenance
+        @raw_contracts = {}
       end
 
       # The member's contract, or nil when it has none of its own. `name` is the Ruby method name.
@@ -28,6 +32,7 @@ module Rigor
         return nil if defs.empty?
 
         annotations = annotations_of(method, defs)
+        @raw_contracts[[owner, scope.to_s, name]] = RawContract.new(types: defs.map(&:type), annotations: annotations)
         return nil if annotations.include?(INFERRED_SIGNATURE)
 
         contract(defs, annotations)

data/lib/rigor/lens/document.rb

@@ -24,7 +24,7 @@ module Rigor
       def to_h
         { "schema" => SCHEMA, "revision" => REVISION, "producer" => producer, "context" => context,
           "capabilities" => CAPABILITIES, "files" => @outcome.targets.map { |target| file(target) },
-          "members" => @outcome.member_rows }
+          "members" => @outcome.member_rows, "claims" => nil }
       end
 
       private

data/lib/rigor/lens/file_reader.rb

@@ -26,7 +26,10 @@ module Rigor
       # `kind` is :module, :class or :singleton. `module_function` is :off, :on (a bare `module_function` written
       # directly in a module body covers the later direct defs) or :unknown (the reading Ruby gives and the one
       # `check`'s tables give could differ, so the later defs are omissions).
-      Body = Struct.new(:current, :uncertain, :detached, :kind, :module_function)
+      # `lexical` is the named part of the body's Ruby cref chain, which a builder block does not extend (Ruby
+      # `class_eval`s the block on the new class, but its constants resolve in the scope that wrote it) and a
+      # `class << self` body extends only with its anonymous singleton class, left out here.
+      Body = Struct.new(:current, :uncertain, :detached, :kind, :module_function, :lexical)
 
       ATTRIBUTE_CALLS = { attr_reader: "reader", attr_writer: "writer", attr_accessor: "accessor" }.freeze
       OMITTED_CALLS = {
@@ -92,7 +95,7 @@ module Rigor
       end
 
       def detached
-        @bodies.push(Body.new("public", false, true, :detached, :off))
+        @bodies.push(Body.new("public", false, true, :detached, :off, @bodies.last&.lexical))
         yield
       ensure
         @bodies.pop
@@ -124,14 +127,14 @@ module Rigor
           return detached { walk(node.body, nesting, singleton: singleton, in_block: true) } if node.body
         end
 
-        walk_body(node.body, nesting, singleton: true, kind: :singleton)
+        walk_body(node.body, nesting, singleton: true, kind: :singleton, lexical: lexical_nesting(nesting))
       end
 
       # A class body's statements, tracking the running visibility and `module_function`.
-      def walk_body(body, nesting, singleton:, kind:)
+      def walk_body(body, nesting, singleton:, kind:, lexical: nesting)
         return if body.nil?
 
-        @bodies.push(Body.new("public", false, false, kind, :off))
+        @bodies.push(Body.new("public", false, false, kind, :off, lexical))
         statements = body.is_a?(Prism::StatementsNode) ? body.body : [body]
         statements.each { |child| walk_body_statement(child, nesting, singleton) }
       ensure
@@ -425,7 +428,7 @@ module Rigor
                                  "block" => nil, "body_return" => nil }, contracts: trailing ? :trailing : false)
         end
         block = node.value.block
-        walk_body(block.body, nesting + [name], singleton: false, kind: :builder) if block&.body
+        walk_body(block.body, nesting + [name], singleton: false, kind: :builder, lexical: nesting) if block&.body
       end
 
       # Ruby forces a field reader named `initialize_copy` (say) private, but not its `Struct` writer: a `Data`
@@ -539,7 +542,9 @@ module Rigor
         data = { "kind" => "method", "name" => node.name.to_s, "owner" => owner, "scope" => scope.to_s,
                  "attribute" => nil, "members" => [node.name.to_s], "module_function" => module_function,
                  "visibility" => module_function ? "private" : visibility(node, nesting, scope),
-                 "params" => shape_params, "block" => shape_block, "body_return" => returns }
+                 "params" => shape_params, "block" => shape_block, "body_return" => returns,
+                 "lexical_nesting" => lexical_nesting(nesting),
+                 "singleton_nesting" => scope == :singleton && node.receiver.nil? }
         return data unless module_function
 
         # Internal to the member pass: the singleton copy is public until `private_class_method` says otherwise,
@@ -549,6 +554,12 @@ module Rigor
         data.merge("singleton_visibility" => "public", "singleton_body_return" => copy)
       end
 
+      # The Ruby cref chain a def written here reads its constants through: the enclosing body's, which differs
+      # from the owner nesting under a builder block.
+      def lexical_nesting(nesting)
+        @bodies.last&.lexical || nesting
+      end
+
       # Whether the instance-scope return may differ from the singleton copy's: the body reads `self`, instance or
       # class state, or `super` (nested defs excluded, blocks included, which over-declines safely), or the return
       # names the owner's type, which is where a `self` that flowed through `itself`, `tap` or another module
@@ -628,13 +639,15 @@ module Rigor
       def alias_site(names, owner)
         new_name, old_name = names
         last, copy = alias_original(owner, old_name)
+        copied = copy&.data || {}
         visibility = FORCED_PRIVATE.include?(new_name) ? "private" : last&.data&.fetch("visibility")
         # `initialize` reads `void` by its name, which neither side of an alias across it keeps.
         returns = copy && ![new_name, old_name].include?("initialize") ? copy.data["body_return"] : nil
         { "kind" => "method", "name" => new_name, "owner" => owner, "scope" => "instance", "attribute" => nil,
           "members" => [new_name], "module_function" => false, "visibility" => visibility,
-          "params" => copy&.data&.fetch("params"), "block" => copy&.data&.fetch("block"),
+          "params" => copied["params"], "block" => copied["block"],
           "body_return" => returns || Slot.unavailable("not_computed"),
+          "lexical_nesting" => copied["lexical_nesting"], "singleton_nesting" => copied["singleton_nesting"],
           "alias_of" => old_name, "aliased_node" => copy && aliased_node(copy) }
       end
 

data/lib/rigor/lens/run.rb

@@ -23,6 +23,12 @@ module Rigor
       Target = Data.define(:argument, :path, :absolute, :status, :reason, :reader, :diagnostics, :inputs)
       Outcome = Data.define(:targets, :member_rows, :plugins, :warm)
 
+      attr_reader :claim_contexts
+
+      def raw_contracts
+        @contract_reader&.raw_contracts || {}
+      end
+
       # @param root — the project root (absolute); every path in the answer is relative to it
       def initialize(configuration:, root:, arguments:, workers:)
         @configuration = configuration
@@ -80,6 +86,7 @@ module Rigor
         @contracts = {}
         @defaulted_blocks = {}
         @site_paths = {}
+        @claim_contexts = {}
       end
 
       # A file requested again, in any spelling, is answered once: the later entries read `duplicate`, naming the
@@ -134,6 +141,7 @@ module Rigor
           end
         end
         @captured[absolute] = reader
+        @claim_contexts[absolute] = scope
       end
 
       # The constant's type as `check` reads it ({Reflection.constant_type_for}): the value the project's source

data/lib/rigor/lens.rb

@@ -10,7 +10,7 @@ module Rigor
     # Bumped on every breaking change to the `lens/v0` document (docs/internal-spec/lens.md § Status).
     REVISION = 1
     CAPABILITIES = %w[class module method attribute constant module_function builder alias body_return
-                      diagnostics inputs].freeze
+                      diagnostics inputs claims].freeze
 
     module_function
 

data/lib/rigor/library_probe.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "environment/required_features"
+
+module Rigor
+  # Issue #2961 — answers what `RBS::EnvironmentLoader#has_library?(version: nil)` answers, for the
+  # {ConfigAudit} library warnings. The CLI has not loaded `rbs` when that audit runs, and loading it costs
+  # ~90 ms on the warm boot-slim path, so without a loaded `rbs` this probes the filesystem instead: a gem's
+  # `sig/` directory, or a release-versioned directory under the bundled rbs gem's `stdlib/<name>/`
+  # (`Repository::GemRBS#load!`). A probe that cannot place the rbs gem answers true: it never warns when unsure.
+  module LibraryProbe
+    module_function
+
+    def predicate
+      if defined?(::RBS::EnvironmentLoader)
+        return ->(lib) { ::RBS::EnvironmentLoader.new.has_library?(library: lib, version: nil) }
+      end
+
+      stdlib = stdlib_root
+      return ->(_lib) { true } if stdlib.nil?
+
+      ->(lib) { gem_sig_dir?(lib) || stdlib_library?(stdlib, lib) }
+    end
+
+    # The names of `library_names` the environment loads: a default library, a vendored feature token, or a name
+    # RBS has. The loader drops any other name (`RbsLoader.library_loader` keeps only `has_library?` ones), so it
+    # covers nothing. The predicate is built only when a name needs it: building it can construct an RBS loader.
+    # Callers have `Environment` loaded, which defines `DEFAULT_LIBRARIES`.
+    def loadable(library_names)
+      has = nil
+      library_names.select do |name|
+        Environment::DEFAULT_LIBRARIES.include?(name) || Environment::RequiredFeatures.feature_of_token(name) ||
+          (has ||= predicate).call(name)
+      end
+    end
+
+    # The `libraries:` names worth auditing: a vendored feature name (`prime`) becomes a vendored feature token
+    # that the loader never asks `has_library?` about, so it is not an RBS library name to check.
+    def auditable(libraries)
+      Array(libraries).map(&:to_s) - Environment::RequiredFeatures::VENDORED_DIRS.keys
+    end
+
+    def stdlib_root
+      dir = File.join(Gem::Specification.find_by_name("rbs").gem_dir, "stdlib")
+      File.directory?(dir) ? dir : nil
+    rescue Gem::LoadError
+      nil
+    end
+
+    def gem_sig_dir?(name)
+      File.directory?(File.join(Gem::Specification.find_by_name(name).gem_dir, "sig"))
+    rescue Gem::MissingSpecError
+      false
+    rescue Gem::LoadError
+      true
+    end
+
+    def stdlib_library?(stdlib, name)
+      return false if name.include?("/") || name.include?("\0")
+
+      Dir.children(File.join(stdlib, name)).any? do |child|
+        Gem::Version.correct?(child) && !Gem::Version.create(child).prerelease?
+      end
+    rescue SystemCallError
+      false
+    end
+  end
+end