type_toolkit 0.0.5 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a743f2b4d2786fb8c08c666974f6f913a4baea59dc9d99dba7a5982ec13441a
-  data.tar.gz: '097ea19c5691a4416de13f1d49ad05544793a9246cd358fcc5619ccca39f6419'
+  metadata.gz: 12374ec2c61c2218bb47b3e2f79d1d7c9bf59a7f4d75d2c429ebeecb02d4d51d
+  data.tar.gz: 13ef655859f7305f5ce532d6f9a3ac53513f2fcc8935d1b1c1f85b07c5f9e5d9
 SHA512:
-  metadata.gz: 66a3f796e922912c0909a4a7548fd72f75a2cee65800a64c37189176cb6bbb323e4693c458b6bef99f828550e83693b036ef3f1e46542a4cf8da547255ed7c76
-  data.tar.gz: 846e557b1e223a17adfc8ad6df338a9032cc3ea983e8f0079881f85f9012b0f20968ffd08f176386504393133cc63124e19a0cdb88b6124bac5452f0f20798b3
+  metadata.gz: 1ef3a56d5b8838ffcd97adf208f2ce67598dfa6157414ba084a91e146d43669ab1b06810659c9b3226ad5cd80f2ac875f937301238f45ba68d918ddabd177fd4
+  data.tar.gz: df81fdc2a72a0146a244a9a1028c227d789db201d3e1f66300a1cb4ccc9caf5345b27474dac8fe858a6f5753ae20bae184380a4837afd1c45da8a9ec4de1f6cf

data/.github/workflows/ci.yml

@@ -19,12 +19,8 @@ jobs:
           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

data/README.md

@@ -70,6 +70,67 @@ last_delivery = user.not_nil!
   .deliveries.last.not_nil!
 ```
 
+The `TypeToolkit/PreferNotNil` RuboCop cop autocorrects `T.must` and `T.must_because` to `.not_nil!`.
+For `T.must_because`, the reason block's source is preserved as comments inside a parenthesized expression,
+so the correction also works in chained calls and nested expressions:
+
+```rb
+# Before
+value = T.must_because(foo) { "Proven non-nil by validation." }
+
+# After
+value = (
+  # Proven non-nil by validation.
+  foo.not_nil!
+)
+```
+
+The reason is documentation only after correction: it is no longer evaluated or included in the exception message.
+Calls with heredocs in the value or reason block are reported but not autocorrected, because heredoc bodies can extend beyond the block's source range.
+
+### Interfaces
+
+Interfaces are modules with abstract methods which a conforming class must implement. They help make duck-typing easier to use in Ruby, by validating that your conforming classes do actually provide the correct methods needed of them.
+
+The Type Toolkit provides runtime support for interfaces (marked with `interface!`) and abstract methods (marked with `abstract` before the `def` keyword).
+
+Example:
+
+```ruby
+module Notifier
+  interface!
+
+  #: (String) -> void
+  abstract def send_notification(message); end
+end
+
+class SlackNotifier
+  include Notifier
+
+  # @override
+  #: (String) -> void
+  def send_notification(message)
+    puts "Posting to Slack API: #{message.inspect}"
+  end
+end
+
+SlackNotifier.new.send_notification("Hello, world!") # ✅
+# => Posting to Slack API: "Hello, world!"
+```
+
+Unimplemented abstract methods cannot be called, and the Type Toolkit runtime will raise an error if you try to do so:
+
+```ruby
+class EmailNotifier
+  include Notifier
+  
+  # Oops, forgot to implement `#send_notification`!
+end
+
+EmailNotifier.new.send_notification("Hello, world!") # ❌ TypeToolkit::AbstractMethodNotImplementedError
+# => Abstract method #send_notification was never implemented.
+```
+
 ## Guiding Principles
 
 ### Blazingly fast™

data/Rakefile

@@ -14,13 +14,6 @@ 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 do |t|

data/benchmark/.rubocop.yml

@@ -0,0 +1,7 @@
+inherit_from: ../.rubocop.yml
+
+Naming/ClassAndModuleCamelCase:
+  Enabled: false # Sometimes underscores are useful, m'kay?
+
+Style/ClassMethodsDefinitions:
+  Enabled: false # We need to be able to compare `class << self` and `def self.`

data/benchmark/abstract_methods_benchmark.rb

@@ -0,0 +1,221 @@
+# typed: ignore
+# frozen_string_literal: true
+
+# Benchmark the performance overhead of calling:
+# - A concrete implementation of an abstract method
+# - An inherited concrete implementation of an abstract method
+# - The error case of calling an unimplemented abstract method
+
+############################################# Results #############################################
+#
+# ruby 3.4.3 (2025-04-14 revision d0b7e5b6a0) +PRISM [arm64-darwin23]
+#
+# ## Interpreter
+#
+# | Call to...        |        Regular impl |          Inherited impl |              Missing impl |
+# |-------------------|--------------------:|------------------------:|--------------------------:|
+# | sorbet-runtime    | (same-ish) 23.02 ns | (2.70x slower) 57.30 ns | (1.13x  slower) 472.86 ns |
+# | manual delegation | (same-ish) 22.18 ns | (2.07x slower) 44.90 ns |               *415.36 ns* |
+# | type_toolkit      | (same-ish) 22.56 ns |              *22.03 ns* | (2.11x  slower) 890.38 ns |
+#
+# ## YJIT#
+# | Call to...        |        Regular impl |           Inherited impl |              Missing impl |
+# |-------------------|--------------------:|-------------------------:|--------------------------:|
+# | sorbet-runtime    |  (same-ish) 1.63 ns | (21.41x slower) 34.91 ns | (1.10x  slower) 447.59 ns |
+# | manual delegation |  (same-ish) 1.63 ns |  (7.15x slower) 11.66 ns |               *405.84 ns* |
+# | type_toolkit      |  (same-ish) 1.67 ns |                *1.63 ns* | (1.91x  slower) 774.91 ns |
+#
+####################################################################################################
+
+require "bundler"
+Bundler.require(:default, :benchmark)
+
+require "type_toolkit"
+
+module TypeKitDemo
+  # Provides the concrete implementation of `m`
+  class Parent
+    def m1 = "Parent#m1"
+  end
+
+  module I
+    interface!
+
+    abstract def m1; end
+    abstract def m2; end
+    abstract def not_implemented; end
+  end
+
+  # Inherits the concrete implementation of `m` from DemoParentClass.
+  class Child < Parent
+    include I
+
+    def m2 = "Child#m2"
+  end
+end
+
+module SorbetRuntimeDemo
+  # Provides the concrete implementation of `m`
+  class Parent
+    def m1 = "Parent#m1"
+  end
+
+  module I
+    extend T::Sig
+    extend T::Helpers
+
+    interface!
+
+    sig { abstract.returns(String) }
+    def m1; end
+
+    sig { abstract.returns(String) }
+    def m2; end
+
+    sig { abstract.returns(String) }
+    def not_implemented; end
+  end
+
+  # Inherits the concrete implementation of `m` from DemoParentClass.
+  class Child < Parent
+    include I
+
+    def m2 = "Child#m2"
+  end
+end
+
+module ManualDelegationDemo
+  class Parent
+    def m1 = "Parent#m1"
+  end
+
+  module I
+    def m1 = defined?(super) ? super : raise
+    def m2 = defined?(super) ? super : raise
+    def not_implemented = defined?(super) ? super : raise
+  end
+
+  # Inherits the concrete implementation of `m` from DemoParentClass.
+  class Child < Parent
+    include I
+
+    def m2 = "Child#m2"
+  end
+end
+
+type_toolkit_object = TypeKitDemo::Child.new
+manual_delegation_object = ManualDelegationDemo::Child.new
+sorbet_runtime_object = SorbetRuntimeDemo::Child.new
+
+[:interpreter, :yjit].each do |mode|
+  if mode == :yjit
+    puts <<~MSG
+
+
+      ================================================================================
+      Enabling YJIT...
+      ================================================================================
+
+
+    MSG
+    RubyVM::YJIT.enable
+  end
+
+  warmup = 5
+  time = 10
+
+  width = ["type_toolkit", "sorbet-runtime", "manual delegation"].max_by(&:length).length
+
+  puts "Benchmark the performance of calling the concrete implementation directly..."
+  Benchmark.ips do |x|
+    x.config(warmup:, time:)
+
+    x.report("type_toolkit".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        type_toolkit_object.m2
+      end
+    end
+
+    x.report("sorbet-runtime".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        sorbet_runtime_object.m2
+      end
+    end
+
+    x.report("manual delegation".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        manual_delegation_object.m2
+      end
+    end
+
+    x.compare!
+  end
+
+  puts "\n\nBenchmark the performance of calling the inherited concrete implementation..."
+  Benchmark.ips do |x|
+    x.config(warmup:, time:)
+
+    x.report("type_toolkit".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        type_toolkit_object.m1
+      end
+    end
+
+    x.report("sorbet-runtime".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        sorbet_runtime_object.m1
+      end
+    end
+
+    x.report("manual delegation".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        manual_delegation_object.m1
+      end
+    end
+
+    x.compare!
+  end
+
+  puts "\n\nTest the performance of calling an unimplemented abstract method..."
+  Benchmark.ips do |x|
+    x.config(warmup:, time:)
+
+    x.report("type_toolkit".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        begin
+          type_toolkit_object.not_implemented
+        rescue AbstractMethodNotImplementedError # rubocop:disable Lint/SuppressedException
+        end
+      end
+    end
+
+    x.report("sorbet-runtime".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        begin
+          sorbet_runtime_object.not_implemented
+        rescue NotImplementedError # rubocop:disable Lint/SuppressedException
+        end
+      end
+    end
+
+    x.report("manual delegation".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        begin
+          manual_delegation_object.not_implemented
+        rescue StandardError # rubocop:disable Lint/SuppressedException
+        end
+      end
+    end
+
+    x.compare!
+  end
+end

data/benchmark/interface_startup_performance.rb

@@ -0,0 +1,128 @@
+# typed: ignore
+# frozen_string_literal: true
+
+# Benchmark the startup performance of declaring modules/interfaces in 3 different styles:
+# - TypeToolkit (abstract gem)
+# - Sorbet runtime
+# - Manual delegation (defined?(super) pattern)
+
+############################################# Results #############################################
+#
+# ruby 3.4.3 (2025-04-14 revision d0b7e5b6a0) +PRISM [arm64-darwin23]
+#
+# |                   |              Interpreter |                       YJIT |
+# |-------------------|-------------------------:|---------------------------:|
+# | sorbet-runtime    | (21.34x slower) 50.79 μs | (152.34x slower) 377.27 μs |
+# | type_toolkit      |  (4.18x slower)  9.95 μs |   (4.18x slower)  10.35 μs |
+# | manual delegation |                  2.38 μs |                    2.48 μs |
+#
+####################################################################################################
+
+require "bundler"
+Bundler.require(:default, :benchmark)
+
+require "type_toolkit"
+
+warmup = 5
+time = 10
+
+width = ["type_toolkit", "sorbet-runtime", "manual delegation"].max_by(&:length).length
+
+puts "Benchmark the time to declare an interface module with abstract methods..."
+
+[:interpreter, :yjit].each do |mode|
+  if mode == :yjit
+    puts <<~MSG
+
+
+      ================================================================================
+      Enabling YJIT...
+      ================================================================================
+
+
+    MSG
+    RubyVM::YJIT.enable
+  end
+
+  Benchmark.ips do |x|
+    x.config(warmup:, time:)
+
+    x.report("type_toolkit".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        interface = Module.new do
+          interface!
+
+          abstract def m1; end
+          abstract def m2; end
+          abstract def m3; end
+        end
+
+        Class.new do
+          include interface
+
+          def m1 = "m1"
+          def m2 = "m2"
+          def m3 = "m3"
+        end
+      end
+    end
+
+    x.report("sorbet-runtime".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        interface = Module.new do
+          extend T::Sig
+          extend T::Helpers
+
+          interface!
+
+          sig { abstract.returns(String) }
+          def m1; end
+
+          sig { abstract.returns(String) }
+          def m2; end
+
+          sig { abstract.returns(String) }
+          def m3; end
+        end
+
+        Class.new do
+          extend T::Sig
+
+          include interface
+
+          sig { override.returns(String) }
+          def m1 = "m1"
+
+          sig { override.returns(String) }
+          def m2 = "m2"
+
+          sig { override.returns(String) }
+          def m3 = "m3"
+        end
+      end
+    end
+
+    x.report("manual delegation".rjust(width)) do |times|
+      i = 0
+      while (i += 1) < times
+        interface = Module.new do
+          def m1 = defined?(super) ? super : raise
+          def m2 = defined?(super) ? super : raise
+          def m3 = defined?(super) ? super : raise
+        end
+
+        Class.new do
+          include interface
+
+          def m1 = "m1"
+          def m2 = "m2"
+          def m3 = "m3"
+        end
+      end
+    end
+
+    x.compare!
+  end
+end

data/benchmark/module_benchmark.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Benchmark if it's worth checking `Module.include?` before calling`Module.include`
+# ... spoiler: meh, not really.
+
+############################################# Results #############################################
+#
+# ruby 3.4.3 (2025-04-14 revision d0b7e5b6a0) +PRISM [arm64-darwin23]
+#
+# |                    |             Interpreter |                    YJIT |
+# |-------------------:|------------------------:|------------------------:|
+# |       just include | (2.39x slower) 54.35 ns | (8.53x slower) 35.29 ns |
+# | check then include |                22.72 ns |                 4.14 ns |
+#
+####################################################################################################
+
+require "bundler"
+Bundler.require(:default, :benchmark)
+
+module M1; end
+module M2; end
+class C1; end
+class C2; end
+
+[:interpreter, :yjit].each do |mode|
+  if mode == :yjit
+    puts <<~MSG
+
+
+      ================================================================================
+      Enabling YJIT...
+      ================================================================================
+
+
+    MSG
+    RubyVM::YJIT.enable
+  end
+
+  warmup = 5
+  time = 10
+
+  puts "Benchmark the performance of calling the concrete implementation directly..."
+  Benchmark.ips do |x|
+    x.config(warmup:, time:)
+
+    x.report("check then include") do |times|
+      i = 0
+      while (i += 1) < times
+        C1.include(M1) unless C1.include?(M1)
+      end
+    end
+
+    x.report("just include") do |times|
+      i = 0
+      while (i += 1) < times
+        C2.include(M2)
+      end
+    end
+
+    x.compare!
+  end
+end

data/config/default.yml

@@ -2,3 +2,8 @@ TypeToolkit/DontExpectUnexpectedNil:
   Description: "Detects misuse of UnexpectedNilError (rescuing, raising, or asserting it)."
   Enabled: true
   VersionAdded: "0.1.0"
+
+TypeToolkit/PreferNotNil:
+  Description: "Replaces T.must and T.must_because assertions with Type Toolkit's not_nil! assertion."
+  Enabled: true
+  VersionAdded: "0.1.0"