rbs 0.2.0

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "rbs"
+
+# 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/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/bin/setup

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

data/bin/sort

@@ -0,0 +1,89 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "rbs"
+
+Members = RBS::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 = RBS::Buffer.new(name: path, content: path.read)
+  sigs = RBS::Parser.parse_signature(buffer)
+
+  sigs.each do |sig|
+    case sig
+    when RBS::AST::Declarations::Class, RBS::AST::Declarations::Module, RBS::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 = RBS::Writer.new(out: out)
+    writer.write sigs
+  end
+end

data/bin/test_runner.rb

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+
+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/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 `arglists` section, which we don't expect to be included the RBS files.
+    - Delete the `arglists` 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 arglists 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
+```

data/docs/sigs.md

@@ -0,0 +1,148 @@
+# Writing Signatures Guide
+
+You can write the signature of your applications and libraries.
+Signature of your Ruby program would help:
+
+1. Understanding the code structure
+2. Finding APIs
+
+And if you ship your gem with signature, the gem users can type check their applications!
+
+## Writing signatures
+
+You first need to write your program's signature.
+See [syntax guide](syntax.md).
+
+## Testing signatures
+
+When you finish writing signature, you may want to test the signature.
+ruby-signature provides a feature to test your signature.
+
+```
+$ RBS_TEST_TARGET='Foo::*' bundle exec ruby -r rbs/test/setup test/foo_test.rb
+```
+
+The test installs instrumentations to spy the method calls and check if arguments/return values are correct with respect to the type of the method in signature.
+If errors are reported by the test, you will fix the signature.
+You will be sure that you ship a correct signature finally.
+
+The instrumentations are implemneted using `Module#prepend`.
+It defines a module with same name of methods, which asserts the type of arguments/return values and calls `super`.
+
+## Type errors
+
+If the test detects type errors, it will print error messages.
+
+### ArgumentTypeError, BlockArgumentTypeError
+
+The message means there is an unexpected type of argument or block argument.
+
+```
+ERROR -- : [Kaigi::Speaker.new] ArgumentTypeError: expected `::String` (email) but given `:"matsumoto@soutaro.com"`
+```
+
+### ArgumentError, BlockArgumentError
+
+The message means there is an unexpected argument or missing argument.
+
+```
+[Kaigi::Speaker.new] ArgumentError: expected method type (size: ::Symbol, email: ::String, name: ::String) -> ::Kaigi::Speaker
+```
+
+### ReturnTypeError, BlockReturnTypeError
+
+The message means the return value from method or block is incorrect.
+
+```
+ERROR -- : [Kaigi::Conference#each_speaker] ReturnTypeError: expected `self` but returns `[#<Kaigi::Speaker:0x00007fb2b249e5a0 @name="Soutaro Matsumoto", @email=:"matsumoto@soutaro.com">]`
+```
+
+### UnexpectedBlockError, MissingBlockError
+
+The errors are reported when required block is not given or unused block is given.
+
+```
+ERROR -- : [Kaigi::Conference#speakers] UnexpectedBlockError: unexpected block is given for `() -> ::Array[::Kaigi::Speaker]`
+```
+
+### UnresolvedOverloadingError
+
+The error means there is a type error on overloaded methods.
+The `ruby-signature` test framework tries to the best error message for overloaded methods too, but it reports the `UnresolvedOverloadingError` when it fails.
+
+## Setting up the test
+
+The design of the signature testing aims to be non-intrusive. The setup is done in two steps:
+
+1. Loading the testing library
+2. Setting up the test through environment variables
+
+### Loading the library
+
+You need to require `rbs/test/setup` for signature testing.
+You can do it using `-r` option through command line argument or the `RUBYOPT` environment variable.
+
+```
+$ ruby -r rbs/test/setup run_tests.rb
+$ RUBYOPT='-rruby/signature/test/setup' rake test
+```
+
+When you are using Bundler, you may need to require `bundler/setup` explicitly.
+
+```
+$ RUBYOPT='-rbundler/setup -rruby/signature/test/setup' bundle exec rake test
+```
+
+### Environment variables
+
+You need to specify `RBS_TEST_TARGET` to run the test, and you can customize the test with the following environment variables.
+
+- `RBS_TEST_SKIP` (optional)
+- `RBS_TEST_OPT` (optional)
+- `RBS_TEST_LOGLEVEL` (optional)
+- `RBS_TEST_RAISE` (optional)
+
+`RBS_TEST_TARGET` is to specify the classes you want to test. `RBS_TEST_TARGET` can contain comma-separated class name pattern, which is one of an exact class name or with wildcard `*`.
+
+- `RBS_TEST_TARGET=Foo::Bar,Foo::Baz` comma separated exact class names
+- `RBS_TEST_TARGET=Foo::*` using wildcard
+
+`RBS_TEST_SKIP` is to skip some of the classes which matches with `RBS_TEST_TARGET`.
+
+`RBS_TEST_OPT` is to pass the options for ruby signature handling.
+You may need to specify `-r` or `-I` to load signatures.
+The default is `-I sig`.
+
+```
+RBS_TEST_OPT='-r set -r pathname -I sig'
+```
+
+`RBS_TEST_LOGLEVEL` can be used to configure log level. Defaults to `info`.
+
+`RBS_TEST_RAISE` may help to debug the type signatures.
+If the environment variable is set, it raises an exception when a type error is detected.
+You can see the backtrace how the type error is caused and debug your program or signature.
+
+So, a typical command line to start the test would look like the following:
+
+```
+$ RBS_TEST_LOGLEVEL=error \
+  RBS_TEST_TARGET='Kaigi::*' \
+  RBS_TEST_SKIP='Kaigi::MonkeyPatch' \
+  RBS_TEST_OPT='-rset -rpathname -Isig -Iprivate' \
+  RBS_TEST_RAISE=true \
+  RUBYOPT='-rbundler/setup -rruby/signature/test/setup' \
+  bundle exec rake test
+```
+
+## Testing tips
+
+### Skipping a method
+
+You can skip installing the instrumentation per-method basis using `rbs:test:skip` annotation.
+
+```
+class String
+  %a{rbs:test:skip} def =~: (Regexp) -> Integer?
+end
+```