rigortype 0.4.2 → 0.4.3

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

data/lib/rigor/lens/document.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "../version"
+require_relative "../cache/engine_source"
+require_relative "../analysis/run_cache_key"
+
+module Rigor
+  module Lens
+    # Assembles the `lens/v0` document (docs/internal-spec/lens.md § Document) from a {Run::Outcome}.
+    class Document
+      SITE_FIELDS = %w[key kind name owner scope attribute members ordinal span contract_span anchor visibility
+                       contract params block body_return].freeze
+
+      def initialize(outcome:, configuration:, root:, config_path:)
+        @outcome = outcome
+        @configuration = configuration
+        @root = root
+        @config_path = config_path
+      end
+
+      def to_h
+        { "schema" => SCHEMA, "revision" => REVISION, "producer" => producer, "context" => context,
+          "capabilities" => CAPABILITIES, "files" => @outcome.targets.map { |target| file(target) },
+          "members" => @outcome.member_rows }
+      end
+
+      private
+
+      def producer
+        identity = begin
+          Cache::EngineSource.process_identity
+        rescue StandardError
+          "unknown"
+        end
+        { "name" => "rigor", "version" => Rigor::VERSION, "engine_source" => identity }
+      end
+
+      def context
+        fields = {
+          "config" => @config_path && relative(File.expand_path(@config_path)),
+          "target_ruby" => @configuration.target_ruby,
+          "rbs_version" => rbs_version,
+          "signature_roots" => signature_roots.map { |root| relative(root) },
+          "signature_digest" => signature_digest,
+          "plugins" => @outcome.plugins,
+          "lockfiles" => lockfiles
+        }
+        fields.merge("digest" => Lens.digest(JSON.generate(fields)))
+      end
+
+      def rbs_version
+        require "rbs"
+        RBS::VERSION
+      end
+
+      def signature_roots
+        Environment.project_signature_roots(@configuration.signature_paths).map { |path| File.expand_path(path.to_s) }
+      end
+
+      def signature_digest
+        listing = signature_roots.flat_map { |root| Dir.glob(File.join(root, "**", "*.rbs")) }.sort.map do |path|
+          "#{relative(path)}\t#{Lens.digest(File.binread(path))}\n"
+        end
+        Lens.digest(listing.join)
+      end
+
+      def lockfiles
+        Analysis::RunCacheKey.resolved_lockfile_paths(@configuration).compact.filter_map do |path|
+          absolute = File.expand_path(path.to_s)
+          next unless File.file?(absolute)
+
+          { "path" => relative(absolute), "digest" => Lens.digest(File.binread(absolute)) }
+        end
+      end
+
+      # Every field is present; those that apply only to some statuses are null elsewhere (lens.md § Files).
+      def file(target)
+        read = %w[ok parse_error].include?(target.status)
+        head = { "argument" => target.argument, "path" => target.status == "not_found" ? nil : target.path,
+                 "status" => target.status, "reason" => target.status == "ok" ? nil : target.reason,
+                 "digest" => file_digest(target, read) }
+        head.merge(analysed_fields(target.status == "ok" ? target : nil))
+            .merge("diagnostics" => read ? target.diagnostics.map { |diagnostic| diagnostic_row(diagnostic) } : nil)
+            .merge("inputs" => target.status == "ok" ? target.inputs : nil)
+      end
+
+      # The digest of the bytes the analysis read; a file that did not parse is read once more.
+      def file_digest(target, read)
+        return nil unless read
+        return target.reader.digest if target.reader
+
+        Lens.digest(File.binread(target.absolute))
+      end
+
+      def analysed_fields(target)
+        reader = target&.reader
+        { "complete" => reader && reader.omissions.empty?, "omissions" => reader&.omissions,
+          "sites" => reader&.sites&.map { |site| site.data.slice(*SITE_FIELDS) } }
+      end
+
+      def diagnostic_row(diagnostic)
+        { "rule" => diagnostic.qualified_rule, "severity" => diagnostic.severity.to_s,
+          "message" => diagnostic.message, "line" => diagnostic.line, "column" => diagnostic.column }
+      end
+
+      def relative(absolute)
+        Pathname(absolute).relative_path_from(Pathname(@root)).to_s
+      end
+    end
+  end
+end