rbs 1.4.0 → 1.6.1

data/core/string_io.rbs

@@ -164,10 +164,9 @@ class StringIO
 
   # See IO#read.
   #
-  def read: (?Integer length, ?String outbuf) -> String?
+  def read: (?int? length, ?string outbuf) -> String?
 
-  def read_nonblock: (Integer len) -> String
-                   | (Integer len, ?String buf) -> String
+  def read_nonblock: (int len, ?string buf) -> String
 
   def readbyte: () -> Integer
 
@@ -179,8 +178,7 @@ class StringIO
   #
   def readlines: (?String sep, ?Integer limit, ?chomp: boolish) -> ::Array[String]
 
-  def readpartial: (Integer maxlen) -> String
-                 | (Integer maxlen, ?String outbuf) -> String
+  def readpartial: (int maxlen, ?string outbuf) -> String
 
   # Reinitializes the stream with the given *other_StrIO* or *string* and *mode*
   # (see StringIO#new).

data/docs/collection.md

@@ -0,0 +1,116 @@
+# RBS Collection manager
+
+`rbs collection` sub command manages third party gems' RBS. In short, it is `bundler` for RBS.
+
+## Requirements
+
+* `git(1)`
+* `Gemfile.lock`
+
+
+## Usage
+
+### Setup
+
+First, generate the configuration file, `rbs_collection.yaml`, with `rbs collection init`.
+
+```console
+$ rbs collection init
+created: rbs_collection.yaml
+
+$ cat rbs_collection.yaml
+# Download sources
+sources:
+  - name: ruby/gem_rbs_collection
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    revision: main
+    repo_dir: gems
+
+# A directory to install the downloaded RBSs
+path: .gem_rbs_collection
+
+gems:
+  # Skip loading rbs gem's RBS.
+  # It's unnecessary if you don't use rbs as a library.
+  - name: rbs
+    ignore: true
+```
+
+I also recommend updating `.gitignore`.
+
+```console
+$ echo /.gem_rbs_collection/ >> .gitignore
+```
+
+### Install dependencies
+
+Then, install gems' RBS with `rbs collection install`! It copies RBS from [the gem RBS repository](https://github.com/ruby/gem_rbs_collection) to `.gem_rbs_collection/` directory by default.
+I recommend to ignore `.gem_rbs_collection/` from version control system, such as Git.
+
+```console
+$ rbs collection install
+Installing ast:2.4 (ruby/gem_rbs_collection@4b1a2a2f64c)
+...
+It's done! 42 gems's RBSs now installed.
+```
+
+Finally the third party RBSs are available! `rbs` commands, such as `rbs validate`, automatically load the third party RBSs.
+
+### Other commands
+
+`rbs collection` has two more commands.
+
+* `rbs collection update` updates `rbs_collection.lock.yaml`.
+* `rbs collection clean` removes unnecessary rbs from `.gem_rbs_collection` directory.
+
+## Configuration
+
+Configure `rbs collection` with editing `rbs_collection.yaml`.
+
+```yaml
+# Download sources.
+# You can add own collection git repository.
+sources:
+  - name: ruby/gem_rbs_collection
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    revision: main
+    repo_dir: gems
+
+# A directory to install the downloaded RBSs
+path: .gem_rbs_collection
+
+gems:
+  # If the Gemfile.lock doesn't contain csv gem but you use csv gem,
+  # you can write the gem name explicitly to install RBS of the gem.
+  - name: csv
+
+  # If the Gemfile.lock contains nokogiri gem but you don't want to use the RBS,
+  # you can ignore the gem.
+  # `rbs collection` avoids to install nokogiri gem's RBS by this change.
+  # It is useful if the nokogiri RBS has a problem, such as compatibility issue with other RBS.
+  - name: nokogiri
+    ignore: true
+```
+
+## Files / Directories
+
+* `rbs_collection.yaml`
+  * The configuration file.
+  * You need to edit it if:
+    * You don't want to ignore gem's RBS.
+    * You want to add gem's RBS explicitly.
+  * You can change the file path with `--collection` option. e.g. `rbs --collection another_conf.yaml collection install`.
+* `rbs_collection.lock.yaml`
+  * RBS installs and loads RBS files with this file.
+  * It is auto-generated file. Do not edit this file.
+  * I recommend to manage it with VCS such as git.
+* `.gem_rbs_collection/`
+  * RBS installs third party RBS files to the directory.
+  * I recommend to ignore it from VCS.
+  * You can change the path with `path` option of `rbs_collection.yaml` file.
+
+
+## How it works
+
+`rbs collection` is integrated with Bundler.
+`rbs collection install` command generates `gem_rbs_collection.lock.yaml` from `gem_rbs_collection.yaml` and `Gemfile.lock`. It uses `Gemfile.lock` to detects dependencies.

data/lib/rbs/builtin_names.rb

@@ -51,5 +51,6 @@ module RBS
     Regexp = Name.define(:Regexp)
     TrueClass = Name.define(:TrueClass)
     FalseClass = Name.define(:FalseClass)
+    Numeric = Name.define(:Numeric)
   end
 end

data/lib/rbs/cli.rb

@@ -6,6 +6,7 @@ module RBS
   class CLI
     class LibraryOptions
       attr_accessor :core_root
+      attr_accessor :config_path
       attr_reader :repos
       attr_reader :libs
       attr_reader :dirs
@@ -16,6 +17,7 @@ module RBS
 
         @libs = []
         @dirs = []
+        @config_path = Collection::Config::PATH
       end
 
       def loader
@@ -25,6 +27,8 @@ module RBS
         end
 
         loader = EnvironmentLoader.new(core_root: core_root, repository: repository)
+        lock = config_path&.then { |p| Collection::Config.lockfile_of(p) }
+        loader.add_collection(lock) if lock
 
         dirs.each do |dir|
           loader.add(path: Pathname(dir))
@@ -52,6 +56,14 @@ module RBS
           self.core_root = nil
         end
 
+        opts.on('--collection PATH', "File path of collection configration (default: #{Collection::Config::PATH})") do |path|
+          self.config_path = Pathname(path).expand_path
+        end
+
+        opts.on('--no-collection', 'Ignore collection configration') do
+          self.config_path = nil
+        end
+
         opts.on("--repo DIR", "Add RBS repository") do |dir|
           repos << dir
         end
@@ -68,7 +80,7 @@ module RBS
       @stderr = stderr
     end
 
-    COMMANDS = [:ast, :list, :ancestors, :methods, :method, :validate, :constant, :paths, :prototype, :vendor, :parse, :test]
+    COMMANDS = [:ast, :list, :ancestors, :methods, :method, :validate, :constant, :paths, :prototype, :vendor, :parse, :test, :collection]
 
     def parse_logging_options(opts)
       opts.on("--log-level LEVEL", "Specify log level (defaults to `warn`)") do |level|
@@ -819,11 +831,90 @@ EOB
 
       # @type var out: String
       # @type var err: String
-      out, err, status = Open3.capture3(env_hash, *args)
+      out, err, status = __skip__ = Open3.capture3(env_hash, *args)
       stdout.print(out)
       stderr.print(err)
 
       status
     end
+
+    def run_collection(args, options)
+      warn "warning: rbs collection is experimental, and the behavior may change until RBS v2.0"
+
+      opts = collection_options(args)
+      params = {}
+      opts.order args.drop(1), into: params
+      config_path = options.config_path or raise
+      lock_path = Collection::Config.to_lockfile_path(config_path)
+
+      case args[0]
+      when 'install'
+        unless params[:frozen]
+          Collection::Config.generate_lockfile(config_path: config_path, gemfile_lock_path: Pathname('./Gemfile.lock'))
+        end
+        Collection::Installer.new(lockfile_path: lock_path, stdout: stdout).install_from_lockfile
+      when 'update'
+        # TODO: Be aware of argv to update only specified gem
+        Collection::Config.generate_lockfile(config_path: config_path, gemfile_lock_path: Pathname('./Gemfile.lock'), with_lockfile: false)
+        Collection::Installer.new(lockfile_path: lock_path, stdout: stdout).install_from_lockfile
+      when 'init'
+        if config_path.exist?
+          puts "#{config_path} already exists"
+          exit 1
+        end
+
+        config_path.write(<<~'YAML')
+          # Download sources
+          sources:
+            - name: ruby/gem_rbs_collection
+              remote: https://github.com/ruby/gem_rbs_collection.git
+              revision: main
+              repo_dir: gems
+
+          # A directory to install the downloaded RBSs
+          path: .gem_rbs_collection
+
+          gems:
+            # Skip loading rbs gem's RBS.
+            # It's unnecessary if you don't use rbs as a library.
+            - name: rbs
+              ignore: true
+        YAML
+        stdout.puts "created: #{config_path}"
+      when 'clean'
+        unless lock_path.exist?
+          puts "#{lock_path} should exist to clean"
+          exit 1
+        end
+        Collection::Cleaner.new(lockfile_path: lock_path)
+      when 'help'
+        puts opts.help
+      else
+        puts opts.help
+        exit 1
+      end
+    end
+
+    def collection_options(args)
+      OptionParser.new do |opts|
+        opts.banner = <<~HELP
+          Usage: rbs collection [install|update|init|clean|help]
+
+          Manage RBS collection, which contains third party RBS.
+
+          Examples:
+
+            # Initialize the configration file
+            $ rbs collection init
+
+            # Generate the lock file and install RBSs from the lock file
+            $ rbs collection install
+
+            # Update the RBSs
+            $ rbs collection update
+        HELP
+        opts.on('--frozen') if args[0] == 'install'
+      end
+    end
   end
 end

data/lib/rbs/collection/cleaner.rb

@@ -0,0 +1,29 @@
+module RBS
+  module Collection
+    class Cleaner
+      attr_reader :lock
+
+      def initialize(lockfile_path:)
+        @lock = Config.from_path(lockfile_path)
+      end
+
+      def clean
+        lock.repo_path.glob('*/*') do |dir|
+          *_, gem_name, version = dir.to_s.split('/')
+          gem_name or raise
+          version or raise
+          next if needed? gem_name, version
+
+          FileUtils.remove_entry_secure(dir.to_s)
+        end
+      end
+
+      def needed?(gem_name, version)
+        gem = lock.gem(gem_name)
+        return false unless gem
+
+        gem['version'] == version
+      end
+    end
+  end
+end

data/lib/rbs/collection/config/lockfile_generator.rb

@@ -0,0 +1,95 @@
+module RBS
+  module Collection
+
+    # This class represent the configration file.
+    class Config
+      class LockfileGenerator
+        attr_reader :config, :lock, :gemfile_lock, :lock_path
+
+        def self.generate(config_path:, gemfile_lock_path:, with_lockfile: true)
+          new(config_path: config_path, gemfile_lock_path: gemfile_lock_path, with_lockfile: with_lockfile).generate
+        end
+
+        def initialize(config_path:, gemfile_lock_path:, with_lockfile:)
+          @config = Config.from_path config_path
+          @lock_path = Config.to_lockfile_path(config_path)
+          @lock = Config.from_path(lock_path) if lock_path.exist? && with_lockfile
+          @gemfile_lock = Bundler::LockfileParser.new(gemfile_lock_path.read)
+        end
+
+        def generate
+          config.gems.each do |gem|
+            assign_gem(gem_name: gem['name'], version: gem['version'])
+          end
+
+          gemfile_lock_gems do |spec|
+            assign_gem(gem_name: spec.name, version: spec.version)
+          end
+          remove_ignored_gems!
+
+          config.dump_to(lock_path)
+          config
+        end
+
+        private def assign_gem(gem_name:, version:)
+          locked = lock&.gem(gem_name)
+          specified = config.gem(gem_name)
+
+          return if specified&.dig('ignore')
+          return if specified&.dig('source') # skip if the source is already filled
+
+          if locked
+            # If rbs_collection.lock.yaml contain the gem, use it.
+            upsert_gem specified, locked
+          else
+            # Find the gem from gem_collection.
+            source = find_source(gem_name: gem_name)
+            return unless source
+
+            installed_version = version
+            best_version = find_best_version(version: installed_version, versions: source.versions({ 'name' => gem_name }))
+            # @type var new_content: RBS::Collection::Config::gem_entry
+            new_content = {
+              'name' => gem_name,
+              'version' => best_version.to_s,
+              'source' => source.to_lockfile,
+            }
+            upsert_gem specified, new_content
+          end
+        end
+
+        private def upsert_gem(old, new)
+          if old
+            old.merge! new
+          else
+            config.add_gem new
+          end
+        end
+
+        private def remove_ignored_gems!
+          config.gems.reject! { |gem| gem['ignore'] }
+        end
+
+        private def gemfile_lock_gems(&block)
+          gemfile_lock.specs.each do |spec|
+            yield spec
+          end
+        end
+
+        private def find_source(gem_name:)
+          sources = config.sources
+
+          sources.find { |c| c.has?({ 'name' => gem_name, 'revision' => nil } ) }
+        end
+
+        private def find_best_version(version:, versions:)
+          candidates = versions.map { |v| Gem::Version.create(v) or raise }
+          return candidates.max || raise unless version
+
+          v = Gem::Version.create(version) or raise
+          Repository.find_best_version(v, candidates)
+        end
+      end
+    end
+  end
+end

data/lib/rbs/collection/config.rb

@@ -0,0 +1,85 @@
+module RBS
+  module Collection
+
+    # This class represent the configration file.
+    class Config
+      class CollectionNotAvailable < StandardError
+        def initialize
+          super <<~MSG
+            rbs collection is not initialized.
+            Run `rbs collection install` to install RBSs from collection.
+          MSG
+        end
+      end
+
+      PATH = Pathname('rbs_collection.yaml')
+
+      # Generate a rbs lockfile from Gemfile.lock to `config_path`.
+      # If `with_lockfile` is true, it respects existing rbs lockfile.
+      def self.generate_lockfile(config_path:, gemfile_lock_path:, with_lockfile: true)
+        LockfileGenerator.generate(config_path: config_path, gemfile_lock_path: gemfile_lock_path, with_lockfile: with_lockfile)
+      end
+
+      def self.from_path(path)
+        new(YAML.load(path.read), config_path: path)
+      end
+
+      def self.lockfile_of(config_path)
+        lock_path = to_lockfile_path(config_path)
+        from_path lock_path if lock_path.exist?
+      end
+
+      def self.to_lockfile_path(config_path)
+        config_path.sub_ext('.lock' + config_path.extname)
+      end
+
+      def initialize(data, config_path:)
+        @data = data
+        @config_path = config_path
+      end
+
+      def add_gem(gem)
+        gems << gem
+      end
+
+      def gem(gem_name)
+        gems.find { |gem| gem['name'] == gem_name }
+      end
+
+      def repo_path
+        @config_path.dirname.join @data['path']
+      end
+
+      def sources
+        @sources ||= (
+          @data['sources']
+            .map { |c| Sources.from_config_entry(c) }
+            .push(Sources::Stdlib.instance)
+            .push(Sources::Rubygems.instance)
+        )
+      end
+
+      def dump_to(io)
+        YAML.dump(@data, io)
+      end
+
+      def gems
+        @data['gems'] ||= []
+      end
+
+      # It raises an error when there are non-available libraries
+      def check_rbs_availability!
+        raise CollectionNotAvailable unless repo_path.exist?
+
+        gems.each do |gem|
+          case gem['source']['type']
+          when 'git'
+            meta_path = repo_path.join(gem['name'], gem['version'], Sources::Git::METADATA_FILENAME)
+            raise CollectionNotAvailable unless meta_path.exist?
+            raise CollectionNotAvailable unless gem == YAML.load(meta_path.read)
+          end
+        end
+      end
+    end
+  end
+end