steep 1.4.0.dev.2 → 1.4.0.dev.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14e9c57b89791ad6d989bddd6439f1ce792ceccf8e17034a1f2ab56c85f2ca41
-  data.tar.gz: dfbe3445dcc72a84a2d4d4e608eb5d74e9da4e1cef03f4979a44e377bf65a917
+  metadata.gz: ef7faa0702c27679ca29580b02273241fcfac188f2462f79a95ea26e633a231d
+  data.tar.gz: b9a7add36c30c5fcb76b89bb5a994fcea4e8749ddb06b9b43d5ebcada4fa51f6
 SHA512:
-  metadata.gz: c14673012d5db258399c4f5d7bda6e3fb6aaca0dbc5c241efca52f8c4e947a5a4fd1a60a42ce6a45e87642926b6e44f65d6058bb241581e5a143251a158f383f
-  data.tar.gz: '0889651d16f198063b243aef34cb300325fb04dcbb7165f0d8c972d7f0f2076d86af77393c8c3f0f216d1a42f6fa8bd2c4cbf78d3e0c106d8c7f883d96099839'
+  metadata.gz: f5b67c4723ec0aec87a215eb874f73ebc62de658b50cc4118399691f9451d0d540ea4640623d94771430839a40399097da2310c98f40e6c50669ceba8d1de026
+  data.tar.gz: d6da7929577c2071c43b6c13ca28b2b0017626ffb760618b2a5551d1824c1c0ba3cbad6c915c522ea1d784caa4bd13ac5364e052972a4573a717c72fd029528d

data/.github/workflows/ruby.yml

@@ -15,7 +15,7 @@ jobs:
         - "3.0"
         - "3.1"
         - "3.2"
-        - "master-nightly-focal"
+        # - "master-nightly-focal"
         task:
         - test
         - test:output
@@ -30,6 +30,5 @@ jobs:
         git config --global --add safe.directory /__w/steep/steep
         ruby -v
         gem install bundler
-        bundle install --jobs 4 --retry 3
         bin/setup
         bundle exec rake ${{matrix.task}}

data/Gemfile

@@ -6,7 +6,7 @@ gemspec
 gem "rbs", "~> 3.0.0"
 
 gem "rake"
-gem "minitest", "~> 5.17"
+gem "minitest", "~> 5.18"
 gem "minitest-hooks"
 group :stackprof, optional: true do
   gem "stackprof"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    steep (1.4.0.dev.2)
+    steep (1.4.0.dev.3)
       activesupport (>= 5.1)
       csv (>= 3.0.9)
       fileutils (>= 1.1.0)
@@ -11,7 +11,6 @@ PATH
       logger (>= 1.3.0)
       parallel (>= 1.0.0)
       parser (>= 3.1)
-      pathname (>= 0.2.1)
       rainbow (>= 2.2.2, < 4.0)
       rbs (>= 2.8.0)
       securerandom (>= 0.1)
@@ -21,7 +20,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.0.4.2)
+    activesupport (7.0.4.3)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
@@ -33,7 +32,7 @@ GEM
       debase-ruby_core_source (>= 0.10.12)
     debase-ruby_core_source (3.2.0)
     ffi (1.15.5)
-    fileutils (1.7.0)
+    fileutils (1.7.1)
     i18n (1.12.0)
       concurrent-ruby (~> 1.0)
     json (2.6.3)
@@ -42,21 +41,20 @@ GEM
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     logger (1.5.3)
-    minitest (5.17.0)
+    minitest (5.18.0)
     minitest-hooks (1.5.0)
       minitest (> 5.3)
     minitest-slow_test (0.2.0)
       minitest (>= 5.0)
     parallel (1.22.1)
-    parser (3.2.1.0)
+    parser (3.2.2.0)
       ast (~> 2.4.1)
-    pathname (0.2.1)
     rainbow (3.1.1)
     rake (13.0.6)
     rb-fsevent (0.11.2)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
-    rbs (3.0.1)
+    rbs (3.0.4)
     ruby-debug-ide (0.7.3)
       rake (>= 0.8.1)
     securerandom (0.2.2)
@@ -73,7 +71,7 @@ PLATFORMS
 
 DEPENDENCIES
   debase (>= 0.2.5.beta2)
-  minitest (~> 5.17)
+  minitest (~> 5.18)
   minitest-hooks
   minitest-slow_test
   rake

data/Gemfile.steep

@@ -1,4 +1,3 @@
 source "https://rubygems.org"
 
-gem 'steep', '~> 1.4.0.dev'
-gem "rbs", "~> 3.0.0.dev"
+gem 'steep', '~> 1.4.0.dev', require: false

data/Gemfile.steep.lock

@@ -1,36 +1,36 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.0.4)
+    activesupport (7.0.4.2)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
       tzinfo (~> 2.0)
     ast (2.4.2)
-    concurrent-ruby (1.1.10)
+    concurrent-ruby (1.2.2)
     csv (3.2.6)
     ffi (1.15.5)
     fileutils (1.7.0)
     i18n (1.12.0)
       concurrent-ruby (~> 1.0)
     json (2.6.3)
-    language_server-protocol (3.17.0.2)
-    listen (3.7.1)
+    language_server-protocol (3.17.0.3)
+    listen (3.8.0)
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     logger (1.5.3)
     minitest (5.17.0)
     parallel (1.22.1)
-    parser (3.2.0.0)
+    parser (3.2.1.0)
       ast (~> 2.4.1)
     pathname (0.2.1)
     rainbow (3.1.1)
     rb-fsevent (0.11.2)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
-    rbs (3.0.0.dev.1)
+    rbs (3.0.4)
     securerandom (0.2.2)
-    steep (1.4.0.dev.1)
+    steep (1.4.0.dev.2)
       activesupport (>= 5.1)
       csv (>= 3.0.9)
       fileutils (>= 1.1.0)
@@ -46,10 +46,10 @@ GEM
       securerandom (>= 0.1)
       strscan (>= 1.0.0)
       terminal-table (>= 2, < 4)
-    strscan (3.0.5)
+    strscan (3.0.6)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
-    tzinfo (2.0.5)
+    tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     unicode-display_width (2.4.2)
 
@@ -58,7 +58,6 @@ PLATFORMS
   arm64-darwin-22
 
 DEPENDENCIES
-  rbs (~> 3.0.0.dev)
   steep (~> 1.4.0.dev)
 
 BUNDLED WITH

data/README.md

@@ -201,13 +201,19 @@ Generally, these are by our design.
 
 `rbs prototype` offers options: `rbi` to generate prototype from Sorbet RBI and `runtime` to generate from runtime API.
 
+## Guides
+
+There are some guides in the `guide` directory. I know we need more comprehensive set of documentations. Just started writing docs.
+
+* [Guides](guides)
+
 ## Examples
 
 You can find examples in `smoke` directory.
 
 ## IDEs
 
-Steep implements some of the Language Server Protocol features. 
+Steep implements some of the Language Server Protocol features.
 - For **VSCode** please install [the plugin](https://github.com/soutaro/steep-vscode)
 - For **SublimeText** please install [LSP](https://github.com/sublimelsp/LSP) package and follow [instructions](https://lsp.sublimetext.io/language_servers/#steep)
 

data/Steepfile

@@ -27,8 +27,6 @@ target :app do
 
   library(
     "rdoc",
-    "set",
-    "pathname",
     "monitor",
     "tsort",
     "uri",
@@ -39,6 +37,5 @@ target :app do
     'find',
     'digest',
     "optparse",
-    "securerandom"
   )
 end

data/bin/rbs

@@ -18,4 +18,3 @@ else
 fi
 
 exec $RBS $@
-

data/guides/README.md

@@ -0,0 +1,5 @@
+# Steep Guides
+
+* [Getting Started with Steep in 5 minutes](src/getting-started/getting-started.md)
+* [Using RBS from gem_rbs_collection](src/gem-rbs-collection/gem-rbs-collection.md)
+* [`nil` and Optional types](src/nil-optional/nil-optional.md)

data/guides/src/gem-rbs-collection/gem-rbs-collection.md

@@ -0,0 +1,143 @@
+# Using RBS from gem_rbs_collection
+
+gem_rbs_collection is a repository of type definitions of gems that are managed by the community. You may find the type definition of a gem that ships without RBS type definitions.
+
+To use RBS files from the repository, you can use rbs-collection subcommand. This guide explains how the command works.
+
+## Quick start
+
+Run rbs-collection-init to start setup.
+
+```
+$ rbs collection init
+```
+
+You have to edit the generated `rbs_collection.yaml` file. Add a few lines under gems section.
+
+```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
+  - name: steep
+    ignore: true
+  - name: rbs_rails     # Add these lines if you use rbs_rails
+    ignore: true
+  - name: rbs_protobuf  # Add these lines if you use rbs_protobuf
+    ignore: true
+```
+
+Once you save the file, run the install command.
+
+```
+$ rbs collection install
+```
+
+That generates `rbs_collection.lock.yaml` and downloads the RBS files from the git repository.
+
+Note that rbs-collection automatically downloads RBS files of gems included in your Bundler environment. You don't have to write all of the gems in your `Gemfile` in `rbs_collection.yaml`.
+
+Finally, we recommend adding the `rbs_collection.yaml` and `rbs_collection.lock.yaml` to your repository, and ignoring `.gem_rbs_collection` directory.
+
+```
+$ git add rbs_collection.yaml
+$ git add rbs_collection.lock.yaml
+$ echo /.gem_rbs_collection >> .gitignore
+$ git commit -m "Set up rbs-collection"
+```
+
+## Updating RBS files
+
+You may want to run rbs-collection-update to update the contents of `rbs_collection.lock.yaml`, when you add a new gem or some gems are updated.
+
+You also need to run rbs-collection-update when the RBS files in the source repository are updated. The type definitions are updated with bug-fixes or improvements, and you need to update to apply the changes to your app.
+
+## Using rbs-collection with Steep
+
+Steep automatically reads `rb_collection.yaml`. You can use Steep immediately without any modifications.
+
+```
+$ bin/steep project    # Show dependencies detected by Steep
+$ bin/steep check      # Run type check
+```
+
+## Migration
+
+If you have used older versions of Steep or RBS, you may have configured libraries manually.
+
+* You have library calls in `Steepfile`
+* You have git submodules in your git repository to download gem_rbs_collection
+
+These are steps to migrate to rbs-collection.
+
+1. Remove unnecessary library configuration
+2. Set up rbs-collection
+3. Validate the configuration
+4. Delete submodule
+
+### 1. Remove unnecessary library configurations
+
+You may have `#library` calls in your Steepfile, or something equivalent in your scripts. We can group the configured libraries into three groups.
+
+1. Gems that is managed by Bundler
+2. Standard libraries (non-gem libs, default gems, and bundled gems)
+    * 2-1) That is a transitive dependency from libraries in group 1
+    * 2-2) That is included in Gemfile.lock
+    * 2-3) Implicitly installed gems – not included in Gemfile
+
+You can delete library configs of 1, 2-1, and 2-2. So, you have to keep the configurations of libraries in 2-3.
+
+Practically, you can remove all library configs and `#library` calls in `Steepfile`, go step 2, run steep check to test, and restore the configs of libraries if error is detected.
+
+### 2. Set up rbs-collection
+
+See the quick start section above!
+
+### 3. Validate the configuration
+
+Run steep check to validate the configuration.
+
+```
+$ bin/steep check
+```
+
+You may see the `UnknownTypeName` error if some libraries are missing. Or some errors that implies duplication or inconsistency of methods/class/module definitions, that may be caused by loading RBS files of a library twice.
+
+Running steep project may help you too. It shows the source files and library directories recognized by Steep.
+
+```
+$ bin/steep project
+```
+
+Note that the type errors detected may change after migrating to rbs-collection, because it typically includes updating to newer versions of RBS files.
+
+### 4. Delete submodule
+
+After you confirmed everything is working correctly, you can delete the submodule. deinit the submodule, remove the directory using git-rm, and delete $GIT_DIR/modules/<name>/.
+
+## What is the rbs_collection.yaml file?
+
+The file mainly defines three properties – sources, gems and path. Sources is essential when you want to create a new RBS file repository, usually for RBS files of the private gems.
+
+Another trick is ignoring RBS files of type checker toolchain. RBS and Steep ships with their own RBS files. However, these RBS files may be unnecessary for you, unless you are not a type checking toolchain developer. It requires some additional gems and RBS files. So adding ignore: true is recommended for the gems.
+
+It seems like we need to add a feature to skip loading RBS files automatically and use the feature for RBS, Steep, and RBS Rails. It looks weird that the gems section is only used to ignore gems.
+
+## Versions of RBS files in gem_rbs_collection
+
+Gem versions in rbs-collection are relatively loosely managed. If a gem is found but the version is different, rbs-collection simply uses the incorrect version.
+
+It will load RBS files of activerecord/6.1 even if your Gemfile specifies activerecord-7.0.4. This is by design with an assumption that having RBS files with some incompatibility is better than having nothing. We see most APIs are compatible even after major version upgrade. Dropping everything for minor API incompatibilities would not make much sense.
+
+That behavior will change in future versions when we see that the assumption is not reasonable and we have better coverage.

data/guides/src/getting-started/getting-started.md

@@ -0,0 +1,164 @@
+# Getting Started with Steep in 5 minutes
+
+## Installing Steep
+
+Add the lines to Gemfile:
+
+```rb
+group :development do
+  gem "steep", require: false
+end
+```
+
+and install the gems.
+
+```
+$ bundle install
+```
+
+You can install it with the gem command.
+
+```
+$ gem install steep
+```
+
+Execute the following command to confirm if the command is successfully installed.
+
+```
+$ steep version
+$ bundle exec steep version         # When you install with bundler
+```
+
+We omit the `bundle exec` prefix from the following commands. Run commands with the prefix if you install Steep with bundler.
+
+## Type checking your first Ruby script
+
+Run steep init command to generate the configuration file, Steepfile.
+
+```
+$ steep init
+```
+
+Open `Steepfile` in your text editor, and replace the content with the following lines:
+
+```rb
+target :lib do
+  signature "sig"
+  check "lib"
+end
+```
+
+Type the following Ruby code in your editor, and save it as `lib/hello.rb`.
+
+```rb
+currencies = { US: "$", JP: "¥", UK: "£" }
+country = %w(US JP UK).sample()
+
+puts "Hello! The price is #{currencies[country.to_sym]}100. 💸"
+```
+
+And type check it with Steep.
+
+```
+$ steep check
+```
+
+The output will report a type error.
+
+```
+# Type checking files:
+
+........................................................F
+
+lib/hello.rb:4:39: [error] Cannot pass a value of type `(::String | nil)` as an argument of type `::Symbol`
+│   (::String | nil) <: ::Symbol
+│     ::String <: ::Symbol
+│       ::Object <: ::Symbol
+│         ::BasicObject <: ::Symbol
+│
+│ Diagnostic ID: Ruby::ArgumentTypeMismatch
+│
+└ puts "Hello! The price is #{currencies[country]}100. 💸"
+                                         ~~~~~~~
+
+Detected 1 problem from 1 file
+```
+
+The error says that the type of the country variable causes a type error. It is expected to be a Symbol, but String or nil will be given.
+
+Let's see how we can fix the error.
+
+## Fixing the type error
+
+The first step is converting the string value to a symbol. We can add to_sym call.
+
+```rb
+currencies = { US: "$", JP: "¥", UK: "£" }
+country = %w(US JP UK).sample()
+
+puts "Hello! The price is #{currencies[country.to_sym]}100. 💸"
+```
+
+The `#to_sym` call will convert a string into a symbol. Does it solve the problem??
+
+```
+$ steep check
+# Type checking files:
+
+........................................................F
+
+lib/hello.rb:4:47: [error] Type `(::String | nil)` does not have method `to_sym`
+│ Diagnostic ID: Ruby::NoMethod
+│
+└ puts "Hello! The price is #{currencies[country.to_sym]}100. 💸"
+                                                 ~~~~~~
+
+Detected 1 problem from 1 file
+```
+
+It detects another problem. The first error was `Ruby::ArgumentTypeMismatch`, but the new error is `Ruby::NoMethod`. The value of `country` may be `nil`, and it doesn't have the `#to_sym` method.
+
+This would be annoying, but one of the most common sources of a type error. The value of an expression may be `nil` unexpectedly, and using the value of the expression may cause an error.
+
+In this case, the `sample()` call introduces the `nil`. `Array#sample()` returns `nil` when the array is empty. We know the receiver of the `sample` call cannot be `nil`, because it is an array literal. But the type checker doesn't know of it. The source code detects the `Array#sample()` method is called, but it ignores the fact that the receiver cannot be empty.
+
+Instead, we can simply tell the type checker that the value of the country cannot be `nil`.
+
+# Satisfying the type checker by adding a guard
+
+The underlying type system supports flow-sensitive typing similar to TypeScript and Rust. It detects conditional expressions testing the value of a variable and propagates the knowledge that the value cannot be `nil`.
+
+We can fix the type error with an or construct.
+
+```rb
+currencies = { US: "$", JP: "¥", UK: "£" }
+country = %w(US JP UK).sample() or raise
+
+puts "Hello! The price is #{currencies[country.to_sym]}100. 💸"
+```
+
+The change let the type checking succeed.
+
+```
+$ steep check
+# Type checking files:
+
+.........................................................
+
+No type error detected. 🧉
+```
+
+The `raise` method is called when `sample()` returns `nil`. Steep can reason the possible control flow based on the semantics of or in Ruby:
+
+* The value of `country` is the return value of `sample()` method call
+* The value of `country` may be `nil`
+  * If the value of `country` is `nil`, the right hand side of the or is evaluated
+  * It calls the `raise` method, which results in an exception and jumps to somewhere
+  * So, when the execution continues to the puts line, the value of `country` cannot be `nil`
+
+There are two possibilities of the type of the result of the `sample()` call, `nil` or a string. We humans can reason that we can safely ignore the case of `nil`. But, the type checker cannot. We have to add `or raise` to tell the type checker it can stop considering the case of `nil` safely.
+
+## Next steps
+
+This is a really quick introduction to using Steep. You may have noticed that I haven't explained anything about defining new classes or modules. See the RBS guide for more examples!
+