steep 0.11.1 → 0.12.0

data/vendor/ruby-signature/bin/annotate-with-rdoc

@@ -0,0 +1,156 @@
+#!/usr/bin/env ruby
+
+require "ruby/signature"
+require "rdoc"
+
+def store_for_class(name, stores:)
+  stores.find do |store|
+    store.find_class_named(name) || store.find_module_named(name)
+  end
+end
+
+def format_comment(comment)
+  out = RDoc::Markup::Document.new
+  out << comment
+  formatter = RDoc::Markup::ToMarkdown.new
+  out.accept(formatter)
+end
+
+def comment_for_constant(decl, stores:)
+  class_name = decl.name.namespace.to_type_name.to_s
+  klass = store_for_class(class_name, stores: stores)&.yield_self {|store|
+    store.find_class_named(class_name) || store.find_module_named(class_name)
+  }
+
+  if klass
+    constant = klass.constants.find do |const|
+      const.name == decl.name.name.to_s
+    end
+
+    if constant&.documented?
+      string = format_comment(constant.comment)
+      Ruby::Signature::AST::Comment.new(location: nil, string: string)
+    end
+  end
+end
+
+def comment_for_class(decl, stores:)
+  name = decl.name.to_s
+  klass = store_for_class(name, stores: stores)&.yield_self {|store|
+    store.find_class_named(name) || store.find_module_named(name)
+  }
+
+  if klass&.documented?
+    string = format_comment(klass.comment)
+    Ruby::Signature::AST::Comment.new(location: nil, string: string)
+  end
+end
+
+def comment_for_method(klass, method, stores:)
+  method = store_for_class(klass, stores: stores)&.load_method(klass, method)
+
+  if method&.documented?
+    out = RDoc::Markup::Document.new
+
+    out << method.comment
+
+    if method.arglists
+      out << RDoc::Markup::Heading.new(1, "arglists 💪👽🚨 << Delete this section")
+      arglists = method.arglists.chomp.split("\n").map {|line| line + "\n" }
+      out << RDoc::Markup::Verbatim.new(*arglists)
+    end
+
+    string = out.accept(RDoc::Markup::ToMarkdown.new)
+    Ruby::Signature::AST::Comment.new(location: nil, string: string)
+  end
+
+rescue RDoc::Store::MissingFileError
+  puts "  👺 No document found for #{klass}#{method}"
+  nil
+end
+
+if ARGV.empty?
+  puts 'annotate-with-rdoc [RBS files...]'
+  exit
+end
+
+def print_members(stores, klass_name, members)
+  members.each do |member|
+    case member
+    when Ruby::Signature::AST::Members::MethodDefinition
+      puts "    Processing #{member.name}..."
+
+      method_name = case
+                    when member.instance?
+                      "##{member.name}"
+                    when member.singleton?
+                      "::#{member.name}"
+                    end
+
+      comment = comment_for_method(klass_name, method_name, stores: stores)
+
+      unless comment
+        if member.instance? && member.name == :initialize
+          comment = comment_for_method(klass_name, '::new', stores: stores)
+        end
+      end
+
+      member.instance_variable_set(:@comment, comment)
+    when Ruby::Signature::AST::Members::AttrReader, Ruby::Signature::AST::Members::AttrAccessor, Ruby::Signature::AST::Members::AttrWriter
+      puts "    👻 Attributes not supported (#{klass_name})"
+    when Ruby::Signature::AST::Members::Alias
+      puts "    Processing #{member.new_name}(alias)..."
+      prefix = case
+               when member.instance?
+                 "#"
+               when member.singleton?
+                 "."
+               end
+      name = "#{prefix}#{member.new_name}"
+
+      comment = comment_for_method(klass_name, name, stores: stores)
+      member.instance_variable_set(:@comment, comment)
+    end
+  end
+end
+
+stores = []
+RDoc::RI::Paths.each true, true, false, false do |path, type|
+  puts "Loading store from #{path}..."
+  store = RDoc::RI::Store.new(path, type)
+  store.load_all
+  stores << store
+end
+
+ARGV.map {|f| Pathname(f) }.each do |path|
+  puts "Opening #{path}..."
+
+  buffer = Ruby::Signature::Buffer.new(name: path, content: path.read)
+  sigs = Ruby::Signature::Parser.parse_signature(buffer)
+
+  sigs.each do |decl|
+    case decl
+    when Ruby::Signature::AST::Declarations::Constant
+      puts "  Importing documentation for #{decl.name}..."
+      comment = comment_for_constant(decl, stores: stores)
+      decl.instance_variable_set(:@comment, comment)
+    when Ruby::Signature::AST::Declarations::Class, Ruby::Signature::AST::Declarations::Module
+      puts "  Importing documentation for #{decl.name}..."
+      comment = comment_for_class(decl, stores: stores)
+      decl.instance_variable_set(:@comment, comment)
+
+      print_members stores, decl.name.to_s, decl.members
+    when Ruby::Signature::AST::Declarations::Extension
+      puts "  Importing documentation for #{decl.name} (#{decl.extension_name})"
+
+      print_members stores, decl.name.to_s, decl.members
+    end
+  end
+
+  puts "Writing #{path}..."
+  path.open('w') do |out|
+    writer = Ruby::Signature::Writer.new(out: out)
+    writer.write sigs
+  end
+end
+

data/vendor/ruby-signature/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "ruby/signature"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/vendor/ruby-signature/bin/query-rdoc

@@ -0,0 +1,103 @@
+#!/usr/bin/env ruby
+
+require "rdoc"
+
+def store_for_class(name, stores:)
+  stores.find do |store|
+    store.find_class_named(name) || store.find_module_named(name)
+  end
+end
+
+def format_comment(comment)
+  out = RDoc::Markup::Document.new
+  out << comment
+  formatter = RDoc::Markup::ToMarkdown.new
+  out.accept(formatter)
+end
+
+def comment_for_constant(name, stores:)
+  *class_components, const_name = name.split(/::/)
+  class_name = class_components.join("::")
+
+  klass = store_for_class(class_name, stores: stores)&.yield_self {|store|
+    store.find_class_named(class_name) || store.find_module_named(class_name)
+  }
+
+  constant = klass.constants.find do |const|
+    const.name == const_name
+  end
+
+  if constant&.documented?
+    format_comment(constant.comment)
+  end
+end
+
+def comment_for_class(class_name, stores:)
+  klass = store_for_class(class_name, stores: stores)&.yield_self {|store|
+    store.find_class_named(class_name) || store.find_module_named(class_name)
+  }
+
+  if klass&.documented?
+    format_comment(klass.comment)
+  end
+end
+
+def comment_for_method(klass, method, stores:)
+  method = store_for_class(klass, stores: stores)&.load_method(klass, method)
+
+  if method&.documented?
+    out = RDoc::Markup::Document.new
+
+    out << method.comment
+
+    if method.arglists
+      out << RDoc::Markup::Heading.new(1, "arglists 💪👽🚨 << Delete this section")
+      arglists = method.arglists.chomp.split("\n").map {|line| line + "\n" }
+      out << RDoc::Markup::Verbatim.new(*arglists)
+    end
+
+    out.accept(RDoc::Markup::ToMarkdown.new)
+  end
+rescue RDoc::Store::MissingFileError
+  nil
+end
+
+if ARGV.empty?
+  puts 'query-rdoc [subject]'
+  puts "  subject ::= ClassName         (class, module, or constant)"
+  puts "            | ClassName.method  (singleton method)"
+  puts "            | ClassName#method  (instance method)"
+  exit
+end
+
+stores = []
+RDoc::RI::Paths.each true, true, false, false do |path, type|
+  STDERR.puts "Loading store from #{path}..."
+  store = RDoc::RI::Store.new(path, type)
+  store.load_all
+  stores << store
+end
+
+subject = ARGV[0]
+
+case
+when match = subject.match(/(?<constant_name>[^#]+)#(?<method_name>.+)/)
+  STDERR.puts "Finding instance method #{match[:constant_name]} # #{match[:method_name]} ..."
+  comment = comment_for_method(match[:constant_name], "##{match[:method_name]}", stores: stores)
+when match = subject.match(/(?<constant_name>[^.]+)\.(?<method_name>.+)/)
+  STDERR.puts "Finding singleton method #{match[:constant_name]} . #{match[:method_name]} ..."
+  comment = comment_for_method(match[:constant_name], "::#{match[:method_name]}", stores: stores)
+else
+  STDERR.puts "Finding class/module/constant #{subject} ..."
+  comment = comment_for_class(subject, stores: stores) || comment_for_constant(subject, stores: stores)
+end
+
+if comment
+  STDERR.puts "Printing document..."
+  comment.each_line do |line|
+    puts "# #{line}"
+  end
+else
+  STDERR.puts "Nothing to print; failed to query the document..."
+  exit 1
+end

data/vendor/ruby-signature/bin/setup

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here
+
+bundle exec rake parser

data/vendor/ruby-signature/bin/sort

@@ -0,0 +1,88 @@
+#!/usr/bin/env ruby
+
+require "ruby/signature"
+
+Members = Ruby::Signature::AST::Members
+
+def group(member)
+  case member
+  when Members::Include, Members::Extend, Members::Prepend
+    0
+  when Members::ClassVariable
+    -3
+  when Members::ClassInstanceVariable
+    -2
+  when Members::InstanceVariable
+    -1
+  when Members::AttrAccessor, Members::AttrWriter, Members::AttrReader
+    2
+  when Members::MethodDefinition
+    if member.singleton?
+      if member.name == :new
+        0.4
+      else
+        1
+      end
+    else
+      if member.name == :initialize
+        0.5
+      else
+        3
+      end
+    end
+  when Members::Alias
+    if member.singleton?
+      1
+    else
+      3
+    end
+  when Members::Private, Members::Public
+    -4
+  end
+end
+
+def key(member)
+  case member
+  when Members::Include, Members::Extend, Members::Prepend
+    member.name.to_s
+  when Members::ClassVariable, Members::ClassInstanceVariable, Members::InstanceVariable
+    member.name.to_s
+  when Members::AttrAccessor, Members::AttrWriter, Members::AttrReader
+    member.name.to_s
+  when Members::MethodDefinition
+    member.name.to_s
+  when Members::Alias
+    member.new_name.to_s
+  else
+    1
+  end
+end
+
+ARGV.map {|f| Pathname(f) }.each do |path|
+  puts "Opening #{path}..."
+
+  buffer = Ruby::Signature::Buffer.new(name: path, content: path.read)
+  sigs = Ruby::Signature::Parser.parse_signature(buffer)
+
+  sigs.each do |sig|
+    case sig
+    when Ruby::Signature::AST::Declarations::Class, Ruby::Signature::AST::Declarations::Module, Ruby::Signature::AST::Declarations::Interface
+      sig.members.sort! do |m1, m2|
+        group1 = group(m1)
+        group2 = group(m2)
+
+        if group1 == group2
+          key(m1) <=> key(m2)
+        else
+          group1 <=> group2
+        end
+      end
+    end
+  end
+
+  puts "Writing #{path}..."
+  path.open('w') do |out|
+    writer = Ruby::Signature::Writer.new(out: out)
+    writer.write sigs
+  end
+end

data/vendor/ruby-signature/bin/test_runner.rb

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+
+RUBY_27_OR_LATER = Gem::Version.new('2.7.0') <= Gem::Version.new(RUBY_VERSION)
+RUBY_27 = Gem::Version.new(RUBY_VERSION).yield_self do |ruby_version|
+  Gem::Version.new('2.7.0') <= ruby_version && ruby_version < Gem::Version.new("2.8.0")
+end
+
+unless RUBY_27
+  STDERR.puts "🚨🚨🚨 stdlib test requires Ruby 2.7 but RUBY_VERSION==#{RUBY_VERSION}, exiting... 🚨🚨🚨"
+  exit
+end
+
+require "pathname"
+
+ARGV.each do |arg|
+  load arg
+end

data/vendor/ruby-signature/docs/CONTRIBUTING.md

@@ -0,0 +1,97 @@
+# Standard Library Signatures Contribution Guide
+
+## Guides
+
+* [Stdlib Signatures Guide](stdlib.md)
+* [Syntax](syntax.md)
+* [Writing Signature Guide](sigs.md)
+
+## Steps for Contribution
+
+1. Pick the class/library you will work for.
+2. Assign yourself on the [work spreadsheet](https://docs.google.com/spreadsheets/d/199rRB93I16H0k4TGZS3EGojns2R0W1oCsN8UPJzOpyU/edit#gid=1383307992) (optional but recommended to avoid duplication).
+3. Sort RBS members (if there is RBS files for the classes).
+    - Use `bin/sort stdlib/path/to/signature.rbs` command and confirm it does not break definitions.
+    - Committing the sorted RBSs is recommended.
+4. Add method prototypes.
+    - Use `rbs prototype runtime --merge CLASS_NAME` command to generate the missing method definitions.
+    - Committing the auto generated signatures is recommended.
+5. Annotate with RDoc.
+    - Use `bin/annotate-with-rdoc stdlib/path/to/signature.rbs` to annotate the RBS files.
+    - Committing the generated annotations is recommended.
+6. Fix method types and comments.
+    - The auto generated RDoc comments include `argslist` section, which we don't expect to be included the RBS files.
+    - Delete the `argslist` sections.
+    - Give methods correct types.
+    - Write tests, if possible. (If it is too difficult to write test, skip it.)
+
+## The Target Version
+
+* The standard library signatures targets Ruby 2.7 for now.
+* The library code targets Ruby 2.6, 2.7, and 3.0.
+
+## Stdlib Worksheet
+
+You can find the list of classes/libraries:
+
+* https://docs.google.com/spreadsheets/d/199rRB93I16H0k4TGZS3EGojns2R0W1oCsN8UPJzOpyU/edit#gid=1383307992
+
+Assign yourself when you start working for a class or library.
+After reviewing and merging your pull request, I will update the status of the library.
+
+You may find the *Good for first contributor* column where you can find some classes are recommended for new contributors (👍), and some classes are not-recommended (👎).
+
+## Useful Tools
+
+* `rbs prototype runtime --merge String`
+  * Generate a prototype using runtime API.
+  * `--merge` tells to use the method types in RBS if exists.
+* `rbs prototype runtime --merge --method-owner=Numeric Integer`
+  * You can use --method-owner if you want to print method of other classes too, for documentation purpose.
+* `bin/annotate-with-rdoc stdlib/builtin/string.rbs`
+  * Write comments using RDoc.
+  * It contains argslist section, but I don't think we should have it in RBS files.
+* `bin/query-rdoc String#initialize`
+  * Print RDoc documents in the format you can copy-and-paste to RBS.
+* `bin/sort stdlib/builtin/string.rbs`
+  * Sort declarations members in RBS files.
+* `rbs validate -r LIB`
+  Validate the syntax and some of the semantics.
+* `rake generate::stdlib_test[String]`
+  Scaffold the stdlib test.
+
+## Standard STDLIB Members Order
+
+We define the standard members order so that ordering doesn't bother reading diffs or git-annotate outputs.
+
+1. `def self.new` or `def initialize`
+2. Mixins
+3. Attributes
+4. Singleton methods
+5. `public` & public instance methods
+6. `private` & private instance methods
+
+```
+class HelloWorld[X]
+  def self.new: [A] () { (void) -> A } -> HelloWorld[A]         # new or initialize comes first
+  def initialize: () -> void
+
+  include Enumerable[X, void]                                   # Mixin comes next
+
+  attr_reader language: (:ja | :en)                             # Attributes
+
+  def self.all_languages: () -> Array[Symbol]                   # Singleton methods
+
+  public                                                        # Public instance methods
+
+  def each: () { (A) -> void } -> void                          # Members are sorted dicionary order
+
+  def to_s: (?Locale) -> String
+
+  private                                                       # Private instance methods
+
+  alias validate validate_locale
+
+  def validate_locale: () -> void
+end
+```