type_toolkit 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d33653934711736d4c8e0eb83bf41f9a28c1393fb21d7c9154b033541073df5
-  data.tar.gz: ad5d09cbe4a290b4890e63b0cc03e177b78704eba0b2d90036813a6c074972e7
+  metadata.gz: d495c6e64eda206b11d7dc9eaaa07bc3eaedfd94e08404ed199e3e8fc55be488
+  data.tar.gz: c3265eb72e3675220942f392f4a67d9df862dfae292b24b3602cd572997448cd
 SHA512:
-  metadata.gz: c47c4644cc21abebafb856e6e9407006ab4e77223f0674b497baccb09d16de6cc11f7c13d6ba54fc4d4b883d8e825567fcc58d4bf6065ef69fa06fa2dbf53f0e
-  data.tar.gz: 1d8b8c1a14700403807e14845e617d10856c9ef8b982675785cbe674b7463038993baa6a51ddcecc5a897e1c1bde28600a268b11efaa673c6eeec68e81435dee
+  metadata.gz: 615492be957fad036838266b6521e5a98f540ca37128b7d116a1524c4e0fa9c412f70933e51edb3465415e1ff390105a040e4072f8b62770f9140cd50789f001
+  data.tar.gz: 17b8774a7b86b8a89081448c56ef834ef463941835b5a48ca9b300e288cf009d48e79acbb3438ca70981f3165ff67d0a49f36539ab6ac7ab706207b0fb29b957

data/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches:
+    - main
+  pull_request:
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    name: CI checks
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@09a7688d3b55cf0e976497ff046b70949eeaccfd # v1.288.0
+        with:
+          bundler-cache: true
+          rubygems: 4.0.4
+      - name: Run type check
+        run: bundle exec rake typecheck
+      - name: Run type check with Prism parser
+        run: bundle exec rake typecheck_prism
+        continue-on-error: true
+      - name: Run tests
+        run: bundle exec rake test
+        continue-on-error: true
+      - name: Lint Ruby files
+        run: bundle exec rake rubocop
+      - name: Verify gem RBIs are up-to-date
+        run: bin/tapioca gem --verify
+      - name: Verify duplicates in shims
+        run: bin/tapioca check-shims

data/README.md

@@ -1,35 +1,126 @@
 # TypeToolkit
 
-TODO: Delete this and the text below, and describe your gem
+[💎 RubyGems](https://rubygems.org/gems/type_toolkit)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/type_toolkit`. To experiment with that code, run `bin/console` for an interactive prompt.
+A minimal runtime library for implementing abstract classes, interfaces, and more.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Install Type Toolkit into your bundle, add it to your `Gemfile`:
 
-Install the gem and add to the application's Gemfile by executing:
+```rb
+gem "type_toolkit"
+```
+
+And then run `bundle install`.
+
+### RuboCop Cops
+
+This gem ships with RuboCop cops that we recommend you enable for your application. You can do so by adding it to the `plugins` list of your `rubocop.yml`:
+
+```yml
+plugins:
+  - rubocop-other-extension
+  - rubocop-type_toolkit
+```
+
+### Cherry-picking features
+
+Simply writing `gem "type_toolkit"` in your `Gemfile` will grab all the tools from the toolkit, which we highly recommend. This adds methods to Ruby's core classes, to make them feel like a native part of the language.
 
-```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+Alternatively, you can cherry-pick only the tools you need. For example, if you only want to use the `not_nil!` assertion, you can add the following to your `Gemfile`:
+
+```rb
+gem "type_toolkit", require: ["type_toolkit/ext/nil_assertions"]
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+or you can skip the require in the `Gemfile`, and later manually require it in a specific file:
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```ruby
+gem "type_toolkit", require: false
 ```
 
-## Usage
+```ruby
+# your_script.rb
+require "type_toolkit/ext/nil_assertions"
+```
 
-TODO: Write usage instructions here
+
+## Tools
+
+### `not_nil!` assertion
+
+When debugging a `nil`-related error, it can be difficult to trace back where the `nil` actually originated from. It could have come in from a parameter, whose argument was read from an instance variable, on an object loaded from a cache, populated by some totally different request.
+
+If a value can't be nil, it's best for that to be clearly asserted as close to where that nilable value was first generated. That way, a rogue `nil` isn't allowed to propagate arbitrarily far away in downstream code.
+
+Type Toolkit provides a `not_nil!` assertion, which will raise an `UnexpectedNilError` if the receiver is `nil`.
+
+```rb
+# `__dir__` can be nil in an "eval", but never in a Ruby file.
+gemfile = Pathname.new(__dir__.not_nil!) / "Gemfile"
+```
+
+`not_nil!` method calls can be chained, to fail early if any value in the chain is `nil`:
+
+```rb
+last_delivery = user.not_nil!
+  .orders.last.not_nil!
+  .deliveries.last.not_nil!
+```
+
+## Guiding Principles
+
+### Blazingly fast™
+
+All tools should aim to have 0 overhead at runtime, as compared to hand-written Ruby.
+
+### Pay only for what you use
+
+There should be no performance cost for a tool that you're not using.
+
+Wherever there's an unavoidable cost, it should only ever apply to code that actually uses the tool. **No global costs.**
+
+Tools should be optimized for the common case, even if that slows them in rare cases. For example, calling an abstract method is as fast as calling any other method, but only if it's implemented. Calling an unimplemented method call hits the `#method_missing` path, which is significantly slower. This is an acceptable trade-off, because no production code should be calling `#method_missing`, anyway.
+
+In all cases, performance costs are quantified and well-documented.
+
+### Feels like Ruby
+
+Tools should feel like part of a programming language itself, and less like its standard library. Type Toolkit takes on the implementation complexity so your code doesn't have to.
+
+To keep that bar high, the toolkit is lean and deliberately focused on
+language-level primitives. Where practical, new
+features should be built in separate libraries that _use_ the Type Toolkit.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+This repo has Rake tasks configured for common development tasks:
+1. `bundle exec rake` to do the next 3 steps all together
+1. `bundle exec rake rubocop` for linting
+1. `bundle exec rake typecheck` to typecheck with Sorbet
+1. `bundle exec rake test` to run all the tests
+1. `bundle exec rake -T` to list all the tasks
+
+### Releasing
+
+This gem is automatically released to [RubyGems.org](https://rubygems.org/gems/type_toolkit) via [Trusted Publishing](https://guides.rubygems.org/trusted-publishing/). To publish a new version of the gem, all you have to do is:
+
+1. Update the version number in [`version.rb`](https://github.com/Shopify/type_toolkit/blob/main/lib/type_toolkit/version.rb)
+    * This can either be part of an existing PR, or a new standalone PR.
+
+2. Once that PR is merged, create a tag at the new head of the `main` branch:
+
+    ```sh
+    git pull origin main && git checkout main && git tag v1.2.3
+    ```
+
+3. Push the new tag.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+    ```sh
+    git push origin v1.2.3
+    ```
 
-## Contributing
+    This will automatically trigger our [release workflow](https://github.com/Shopify/type_toolkit/actions/workflows/release.yml). It must be approved by a member of the Ruby and Rails Infrastructure team at Shopify before it will run.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/type_toolkit.
+Once approved, the workflow will automatically publish the new gem version to RubyGems.org, and create a new [GitHub release](https://github.com/Shopify/type_toolkit/releases).

data/Rakefile

@@ -1,12 +1,36 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
+
+desc "Type-check the code base with Sorbet"
+task :typecheck do
+  sh "bundle exec srb tc" do |ok, _res|
+    abort unless ok
+  end
+end
+
+# Aliases for common names for this task.
+desc "alias for typecheck"; task tc: :typecheck
+desc "alias for typecheck"; task srb: :typecheck
+desc "alias for typecheck"; task sorbet: :typecheck
+
+desc "Type-check the code base with Sorbet using Prism"
+task :typecheck_prism do
+  sh "bundle exec srb tc --parser=prism" do |ok, _res|
+    abort unless ok
+  end
+end
+
 require "minitest/test_task"
 
-Minitest::TestTask.create
+Minitest::TestTask.create do |t|
+  t.libs.delete("test")
+  t.libs << "spec"
+  t.test_globs = ["spec/**/*_spec.rb"]
+end
 
 require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-task default: %i[test rubocop]
+task default: [:typecheck, :test, :rubocop]

data/config/default.yml

@@ -0,0 +1,4 @@
+TypeToolkit/DontExpectUnexpectedNil:
+  Description: "Detects misuse of UnexpectedNilError (rescuing, raising, or asserting it)."
+  Enabled: true
+  VersionAdded: "0.1.0"

data/lib/rubocop/cop/type_toolkit/dont_expect_unexpected_nil.rb

@@ -0,0 +1,115 @@
+# typed: true
+# frozen_string_literal: true
+
+require "type_toolkit/ext/nil_assertions"
+
+module RuboCop
+  module Cop
+    module TypeToolkit
+      # This cop detects attempts to raise, rescue, or otherwise use the `UnexpectedNilError` class.
+      class DontExpectUnexpectedNil < Base
+        RESTRICT_ON_SEND = [:assert_raises, :raise].freeze
+
+        UNEXPECTED_NIL_ERROR_NAME = ::TypeToolkit::UnexpectedNilError.name.not_nil!
+          .split("::").last.not_nil!
+          .to_sym #: Symbol
+        private_constant :UNEXPECTED_NIL_ERROR_NAME
+
+        #: (RuboCop::AST::SendNode) -> void
+        def on_send(node)
+          case node.method_name
+          when :raise then check_raise(node)
+          when :assert_raises then check_assert_raises(node)
+          end
+        end
+
+        #: (RuboCop::AST::ResbodyNode) -> void
+        def on_resbody(node)
+          if (rescued_cls = node.exceptions.find { |ex_class| ex_class.const_type? && unexpected_nil_error?(ex_class) })
+            message = "It is always a mistake for `not_nil!` to be called on nil, " \
+              "so you should never try to rescue `UnexpectedNilError` specifically. " \
+              "Change your code to gracefully handle `nil` instead."
+            add_offense(rescued_cls, message:)
+            ignore_const_node(rescued_cls)
+          end
+        end
+
+        # This is a catch-all for cases where the `UnexpectedNilError` class is used outside of a raise, rescue, etc.
+        #: (RuboCop::AST::ConstNode) -> void
+        def on_const(node)
+          # Don't report this node right away, in case its parent AST is reported by one of the other cases.
+          # Instead, record it for now, and maybe report it at the end of the investigation.
+          if unexpected_nil_error?(node)
+            @const_read_nodes ||= Set.new.compare_by_identity
+            @const_read_nodes << node
+          end
+        end
+
+        # @override
+        #: -> void
+        def on_investigation_end
+          @const_read_nodes&.each do |node|
+            next if @ignored_const_nodes&.include?(node)
+
+            message = "`UnexpectedNilError` should only ever be used by `#not_nil!`."
+            add_offense(node, message:)
+          end
+
+          super
+        end
+
+        private
+
+        #: (RuboCop::AST::ConstNode) -> bool
+        def unexpected_nil_error?(node)
+          return false unless node.short_name == UNEXPECTED_NIL_ERROR_NAME
+
+          ns = node.namespace
+          return true if ns.nil? || ns.cbase_type?
+
+          ns.const_type? && ns.short_name == :TypeToolkit && (ns.namespace.nil? || ns.namespace.cbase_type?)
+        end
+
+        # Check for `raise UnexpectedNilError`
+        #: (RuboCop::AST::SendNode) -> void
+        def check_raise(node)
+          constant = case (first_arg = node.arguments.first)
+          when RuboCop::AST::ConstNode
+            node.arguments.first
+          when RuboCop::AST::SendNode
+            return unless first_arg.method_name == :new && first_arg.receiver.const_type?
+
+            first_arg.receiver
+          else return
+          end
+
+          if unexpected_nil_error?(constant)
+            message = "`UnexpectedNilError` should only ever be raised by `NilClass#not_nil!`."
+            add_offense(node, message:)
+            ignore_const_node(constant)
+          end
+        end
+
+        # Check for `assert_raises UnexpectedNilError`
+        #: (RuboCop::AST::SendNode) -> void
+        def check_assert_raises(node)
+          if (constants = node.arguments.filter { |arg| arg.const_type? && unexpected_nil_error?(arg) }).any?
+            message = "It is always a mistake for `not_nil!` to be called on nil, " \
+              "so tests should not expect any code to raise `UnexpectedNilError`. " \
+              "Change your code to gracefully handle `nil` instead."
+            add_offense(node, message:)
+            ignore_const_node(*constants)
+          end
+        end
+
+        # Call this when this constant node is part of a node tree that already has an offense.
+        # This way we don't report a second offense for the same constant.
+        #: (*RuboCop::AST::ConstNode) -> void
+        def ignore_const_node(*nodes)
+          @ignored_const_nodes ||= Set.new.compare_by_identity
+          @ignored_const_nodes.merge(nodes)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop-type_toolkit.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+RuboCop::ConfigLoader.inject_defaults!(File.join(__dir__, "..", "config", "default.yml"))
+
+require_relative "rubocop/cop/type_toolkit/dont_expect_unexpected_nil"

data/lib/type_toolkit/ext/nil_assertions.rb

@@ -0,0 +1,36 @@
+# typed: true
+# frozen_string_literal: true
+
+# Asserts that the receiver is not nil.
+#
+# You should use `not_nil!` in places where you're absolutely sure a `nil` value can't occur.
+# This should be done as closely to where the value is created as possible, so that the `nil`
+# value doesn't have a chance to be passed around the system. This way, failures occur close to
+# the source of the problem, and are easier to fix.
+module Kernel
+  #: -> self
+  def not_nil!
+    self
+  end
+end
+
+class NilClass
+  # @override
+  #: -> bot
+  def not_nil!
+    raise TypeToolkit::UnexpectedNilError
+  end
+end
+
+module TypeToolkit
+  # An error raised when calling `#not_nil!` on a `nil` value.
+  #
+  # `UnexpectedNilError` should never occur in well-formed code, so it should never be rescued.
+  # This is why it inherits from `Exception` instead of `StandardError`,
+  # so that bare rescues clauses (like `rescue => e`) don't rescue it.
+  class UnexpectedNilError < Exception # rubocop:disable Lint/InheritException
+    def initialize(message = "Called `not_nil!` on nil.")
+      super
+    end
+  end
+end

data/lib/type_toolkit/version.rb

@@ -1,5 +1,6 @@
+# typed: strong
 # frozen_string_literal: true
 
 module TypeToolkit
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/type_toolkit.rb

@@ -1,8 +1,8 @@
+# typed: strong
 # frozen_string_literal: true
 
 require_relative "type_toolkit/version"
+require_relative "type_toolkit/ext/nil_assertions"
 
 module TypeToolkit
-  class Error < StandardError; end
-  # Your code goes here...
 end

data/sorbet/config

@@ -0,0 +1,7 @@
+--dir
+.
+--ignore=tmp/
+--ignore=vendor/
+--enable-experimental-rbs-comments
+--suppress-payload-superclass-redefinition-for=RDoc::Markup::Heading
+--disable-watchman

data/sorbet/rbi/annotations/.gitattributes

@@ -0,0 +1 @@
+**/*.rbi linguist-vendored=true

data/sorbet/rbi/annotations/minitest.rbi

@@ -0,0 +1,120 @@
+# typed: true
+
+# DO NOT EDIT MANUALLY
+# This file was pulled from a central RBI files repository.
+# Please run `bin/tapioca annotations` to update it.
+
+module Minitest::Assertions
+  sig { params(test: T.anything, msg: T.anything).returns(TrueClass) }
+  def assert(test, msg = nil); end
+
+  sig { params(obj: T.anything, msg: T.anything).returns(TrueClass) }
+  def assert_empty(obj, msg = nil); end
+
+  sig { params(exp: T.anything, act: T.anything, msg: T.anything).returns(TrueClass) }
+  def assert_equal(exp, act, msg = nil); end
+
+  sig { params(exp: T.anything, act: T.anything, delta: Numeric, msg: T.anything).returns(TrueClass) }
+  def assert_in_delta(exp, act, delta = T.unsafe(nil), msg = nil); end
+
+  sig { params(a: T.anything, b: T.anything, epsilon: Numeric, msg: T.anything).returns(TrueClass) }
+  def assert_in_epsilon(a, b, epsilon = T.unsafe(nil), msg = nil); end
+
+  sig { params(collection: T.anything, obj: T.anything, msg: T.anything).returns(TrueClass) }
+  def assert_includes(collection, obj, msg = nil); end
+
+  sig { params(cls: T.anything, obj: T.anything, msg: T.anything).returns(TrueClass) }
+  def assert_instance_of(cls, obj, msg = nil); end
+
+  sig { params(cls: T.anything, obj: T.anything, msg: T.anything).returns(TrueClass) }
+  def assert_kind_of(cls, obj, msg = nil); end
+
+  sig { params(matcher: T.any(String, Regexp), obj: T.anything, msg: T.anything).returns(MatchData) }
+  def assert_match(matcher, obj, msg = nil); end
+
+  sig { params(obj: T.anything, msg: T.anything).returns(TrueClass) }
+  def assert_nil(obj, msg = nil); end
+
+  sig { params(o1: T.anything, op: T.any(Symbol, String), o2: T.anything, msg: T.anything).returns(TrueClass) }
+  def assert_operator(o1, op, o2 = T.unsafe(nil), msg = nil); end
+
+  sig { params(stdout: T.nilable(T.any(String, Regexp)), stderr: T.nilable(T.any(String, Regexp)), block: T.proc.void).returns(T::Boolean) }
+  def assert_output(stdout = nil, stderr = nil, &block); end
+
+  sig { params(path: T.any(String, Pathname), msg: T.anything).returns(TrueClass) }
+  def assert_path_exists(path, msg = nil); end
+
+  sig { params(block: T.proc.void).returns(TrueClass) }
+  def assert_pattern(&block); end
+
+  sig { params(o1: T.anything, op: T.any(String, Symbol), msg: T.anything).returns(TrueClass) }
+  def assert_predicate(o1, op, msg = nil); end
+
+  sig { params(exp: NilClass, block: T.proc.void).returns(StandardError) }
+  sig { type_parameters(:T).params(exp: T.any(T::Class[T.type_parameter(:T)], Regexp, String), block: T.proc.void).returns(T.type_parameter(:T)) }
+  def assert_raises(*exp, &block); end
+
+  sig { params(obj: T.anything, meth: T.any(String, Symbol), msg: T.anything, include_all: T::Boolean).returns(TrueClass) }
+  def assert_respond_to(obj, meth, msg = nil, include_all: false); end
+
+  sig { params(exp: T.anything, act: T.anything, msg: T.anything).returns(TrueClass) }
+  def assert_same(exp, act, msg = nil); end
+
+  # @version < 6.0.0
+  sig { params(send_ary: T::Array[T.anything], m: T.anything).returns(T::Boolean) }
+  def assert_send(send_ary, m = nil); end
+
+  sig { params(block: T.proc.void).returns(T::Boolean) }
+  def assert_silent(&block); end
+
+  sig { params(sym: Symbol, msg: T.anything, block: T.proc.void).returns(T.anything) }
+  def assert_throws(sym, msg = nil, &block); end
+
+  sig { params(test: T.anything, msg: T.anything).returns(TrueClass) }
+  def refute(test, msg = nil); end
+
+  sig { params(obj: T.anything, msg: T.anything).returns(TrueClass) }
+  def refute_empty(obj, msg = nil); end
+
+  sig { params(exp: T.anything, act: T.anything, msg: T.anything).returns(TrueClass) }
+  def refute_equal(exp, act, msg = nil); end
+
+  sig { params(exp: T.anything, act: T.anything, delta: Numeric, msg: T.anything).returns(TrueClass) }
+  def refute_in_delta(exp, act, delta = T.unsafe(nil), msg = nil); end
+
+  sig { params(a: T.anything, b: T.anything, epsilon: Numeric, msg: T.anything).returns(TrueClass) }
+  def refute_in_epsilon(a, b, epsilon = T.unsafe(nil), msg = nil); end
+
+  sig { params(collection: T.anything, obj: T.anything, msg: T.anything).returns(TrueClass) }
+  def refute_includes(collection, obj, msg = nil); end
+
+  sig { params(cls: T.anything, obj: T.anything, msg: T.anything).returns(TrueClass) }
+  def refute_instance_of(cls, obj, msg = nil); end
+
+  sig { params(cls: T.anything, obj: T.anything, msg: T.anything).returns(TrueClass) }
+  def refute_kind_of(cls, obj, msg = nil); end
+
+  sig { params(matcher: T.any(String, Regexp), obj: T.anything, msg: T.anything).returns(TrueClass) }
+  def refute_match(matcher, obj, msg = nil); end
+
+  sig { params(obj: T.anything, msg: T.anything).returns(TrueClass) }
+  def refute_nil(obj, msg = nil); end
+
+  sig { params(block: T.proc.void).returns(TrueClass) }
+  def refute_pattern(&block); end
+
+  sig { params(o1: T.anything, op: T.any(Symbol, String), o2: T.anything, msg: T.anything).returns(TrueClass) }
+  def refute_operator(o1, op, o2 = T.unsafe(nil), msg = nil); end
+
+  sig { params(path: T.any(String, Pathname), msg: T.anything).returns(TrueClass) }
+  def refute_path_exists(path, msg = nil); end
+
+  sig { params(o1: T.anything, op: T.any(String, Symbol), msg: T.anything).returns(TrueClass) }
+  def refute_predicate(o1, op, msg = nil); end
+
+  sig { params(obj: T.anything, meth: T.any(String, Symbol), msg: T.anything, include_all: T::Boolean).returns(TrueClass) }
+  def refute_respond_to(obj, meth, msg = nil, include_all: false); end
+
+  sig { params(exp: T.anything, act: T.anything, msg: T.anything).returns(TrueClass) }
+  def refute_same(exp, act, msg = nil); end
+end