rbs-trace 0.3.2 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e587e127bc2689a2d6e3c9f25dad32a5b75b49164b8666d0c0ff891d9c6e35f4
-  data.tar.gz: 47cb65ce7cef30a14cc68984e7a76614ca593a1581a439b34341386937c65591
+  metadata.gz: 4040f1116ab68a5b072e7a847480080c778b1ff87c37a0a47d1ee3b923f61ffb
+  data.tar.gz: b262f219610e463cdccfa5d7e3442526963f118d2ea1386ff442919920b9053f
 SHA512:
-  metadata.gz: 3ccd45b222189e14609f8ef30f207341dbf6a4ed863a4c94b5cf051d28504f84cd8d101a68905de787ac5661f9bc7b9432162b81abbda85868e40e14cc741ebd
-  data.tar.gz: 158f74515cad425793edcc6f7d68c2ee8140afb36d9922ee80b6d1c21c020db748c9842c9b3bc6c15d330c2a12834681c6082b3e373c9ae669ccc379337ed626
+  metadata.gz: e3e1eea5dc319b4eafd62e62ffc1dc10ccc3301ffa603ddd8696f9b0a9a8f16a7604037873595fd91291211264e79622e8f1eba05a22dd02e78133466ae35e7d
+  data.tar.gz: 30f08d4582741295df623ab8ddf1f87c97723eeea0a8217e39a6ae4bcd12dd6a1ee88623256d96e29a83a410687ec8e3fa89a3ce95a72973dc5ad1002846481d

data/.rubocop.yml

@@ -1,6 +1,7 @@
 require:
   - rubocop-rake
   - rubocop-rspec
+  - rubocop-performance
 
 AllCops:
   TargetRubyVersion: 3.1
@@ -16,7 +17,7 @@ Style/Documentation:
   Enabled: false
 
 RSpec/ExampleLength:
-  Max: 15
+  Max: 50
 
 Naming/MethodParameterName:
   Enabled: false
@@ -25,8 +26,18 @@ Naming/FileName:
   Exclude:
     - "lib/rbs-trace.rb"
 
+Naming/VariableNumber:
+  Enabled: false
+
 Layout/LeadingCommentSpace:
   Enabled: false
 
 Style/AccessorGrouping:
   Enabled: false
+
+RSpec/DescribeClass:
+  Exclude:
+    - "spec/smoke_spec.rb"
+
+RSpec/MultipleExpectations:
+  Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 ## [Unreleased]
 
+## [0.4.1] - 2025-02-24
+
+- fix: Ensure class names are referenced
+- fix: Prefer other types over void and untyped
+- fix: Fix process to guess return value as void
+- fix: Do not parse if the caller is not Ruby
+- chore: Auto correct with rubocop-performance
+
+## [0.4.0] - 2025-02-23
+
+- feat: Implement the function to save as RBS files
+- feat: Add CLI commands to support parallel testing
+- fix: Ignore if path is "inline template"
+
+### BREAKING CHANGE
+
+- chore!: Re-design API
+
+```ruby
+# before
+tracing = RBS::Trace::MethodTracing.new
+tracing.enable do
+  # something
+end
+tracing.insert_rbs
+
+# after
+trace = RBS::Trace.new
+trace.enable do
+  # something
+end
+trace.save_comments
+```
+
 ## [0.3.2] - 2024-12-29
 
 - fix: Do not insert comments if comment `#:` exists

data/README.md

@@ -1,9 +1,10 @@
 [![Gem Version](https://badge.fury.io/rb/rbs-trace.svg)](https://badge.fury.io/rb/rbs-trace)
 [![Test](https://github.com/sinsoku/rbs-trace/actions/workflows/test.yml/badge.svg)](https://github.com/sinsoku/rbs-trace/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/sinsoku/rbs-trace/graph/badge.svg?token=rEsPe8Quyu)](https://codecov.io/gh/sinsoku/rbs-trace)
 
 # RBS::Trace
 
-RBS::Trace collects argument types and return value types using TracePoint, and inserts inline RBS type declarations into files.
+RBS::Trace automatically collects argument and return types and saves RBS type declarations as RBS files or comments.
 
 ## Installation
 
@@ -36,21 +37,22 @@ class User
 end
 ```
 
-Call target methods within the `enable` method block, and call the `insert_rbs` method.
+Call target methods within the `enable` method block, and call the `save_comments` method.
 
 ```ruby
-tracing = RBS::Trace::MethodTracing.new
+trace = RBS::Trace.new
 
 # Collects the types of methods called in the block.
-tracing.enable do
+trace.enable do
   user = User.new("Nanoha", "Takamachi")
   user.say_hello
 end
 
-tracing.insert_rbs
+# Save RBS type declarations as embedded comments
+trace.save_comments
 ```
 
-Automatically inserts inline RBS definitions into the file.
+Automatically insert comments into the file.
 
 ```ruby
 class User
@@ -79,36 +81,28 @@ end
 Add the following code to `spec/support/rbs_trace.rb`.
 
 ```ruby
-return unless ENV["RBS_TRACE"]
-
 RSpec.configure do |config|
-  tracing = RBS::Trace::MethodTracing.new
+  trace = RBS::Trace.new
 
-  config.before(:suite) { tracing.enable }
+  config.before(:suite) { trace.enable }
   config.after(:suite) do
-    tracing.disable
-    tracing.insert_rbs
+    trace.disable
+    trace.save_comments
   end
 end
 ```
 
-Then run RSpec with the environment variables.
-
-```console
-$ RBS_TRACE=1 bundle exec rspec
-```
-
 ### Minitest
 
 Add the following code to `test_helper.rb`.
 
 ```ruby
-tracing = RBS::Trace::MethodTracing.new
-tracing.enable
+trace = RBS::Trace.new
+trace.enable
 
 Minitest.after_run do
-  tracing.disable
-  tracing.insert_rbs
+  trace.disable
+  trace.save_comments
 end
 ```
 
@@ -117,11 +111,37 @@ end
 ### Insert RBS declarations for specific files only
 
 ```ruby
-tracing.files.each do |path, file|
+trace.files.each do |path, file|
   file.rewrite if path.include?("app/models/")
 end
 ```
 
+### Save RBS declarations as files
+
+```ruby
+trace.save_files(out_dir: "sig/trace/")
+```
+
+### Parallel testing
+
+If you are using a parallel testing gem such as [parallel_tests](https://github.com/grosser/parallel_tests) or [flatware](https://github.com/briandunn/flatware), first save the type definitions in RBS files.
+
+```ruby
+trace.save_files(out_dir: "tmp/sig-#{ENV["TEST_ENV_NUMBER"]}")
+```
+
+Then use `rbs-trace merge` to merge multiple RBS files into one.
+
+```bash
+$ rbs-trace merge --sig-dir='tmp/sig-*' > sig/merged.rbs
+```
+
+Finally, insert comments using the merged RBS files.
+
+```bash
+$ rbs-trace inline --rb-dir=app --rb-dir=lib
+```
+
 ### Enable debug logging
 
 If you want to enable debug logging, specify the environment variable `RBS_TRACE_DEBUG`.
@@ -142,4 +162,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Rbs::Trace project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/sinsoku/rbs-trace/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the RBS::Trace project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/sinsoku/rbs-trace/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -12,6 +12,13 @@ RuboCop::RakeTask.new
 desc "Generate rbs files"
 task :rbs_inline do
   sh "rbs-inline --output --opt-out lib"
+
+  # If the Ruby file is deleted, delete the RBS file
+  Dir.glob("sig/generated/**/*.rbs").each do |path|
+    rbs_path = Pathname(path)
+    rb_path = rbs_path.sub(%r{^sig/generated}, "lib").sub_ext(".rb")
+    rbs_path.delete unless File.exist?(rb_path)
+  end
 end
 
 desc "Run Steep"

data/exe/rbs-trace

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require "rbs-trace"
+RBS::Trace::CLI.new.run

data/lib/rbs/trace/builder.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module RBS
+  class Trace
+    class Builder # rubocop:disable Metrics/ClassLength
+      include Helpers
+
+      UNBOUND_CLASS_METHOD = Object.instance_method(:class)
+      UNBOUND_NAME_METHOD = Class.instance_method(:name)
+      private_constant :UNBOUND_CLASS_METHOD, :UNBOUND_NAME_METHOD
+
+      GENERICS_SIZE = {
+        Array => 1,
+        Range => 1,
+        Hash => 2
+      }.freeze
+      private_constant :GENERICS_SIZE
+
+      # @rbs (bind: Binding, parameters: Array[__todo__], void: bool) -> Array[__todo__]
+      def method_call(bind:, parameters:, void:)
+        method_type = parse_parameters(bind, parameters)
+        return_type = type_void if void
+
+        [method_type, return_type].tap do |types|
+          stack_traces << types
+        end
+      end
+
+      # @rbs (__todo__) -> AST::Members::MethodDefinition::Overload
+      def method_return(return_value)
+        method_type, return_type = stack_traces.pop
+
+        type = return_type || parse_object(return_value)
+        new_type = method_type.type.with_return_type(type)
+        method_type = method_type.update(type: new_type) # rubocop:disable Style/RedundantSelfAssignment
+
+        AST::Members::MethodDefinition::Overload.new(method_type:, annotations: [])
+      end
+
+      private
+
+      def stack_traces
+        @stack_traces ||= {} #: Hash[Thread, Array[__todo__]]
+        @stack_traces[Thread.current] ||= [] # steep:ignore UnannotatedEmptyCollection
+      end
+
+      # @rbs (Binding, Array[__todo__]) -> MethodType
+      def parse_parameters(bind, parameters) # rubocop:disable Metrics
+        fn = Types::Function.empty(type_void)
+
+        parameters.each do |kind, name| # rubocop:disable Metrics/BlockLength
+          case kind
+          when :req
+            value = bind.local_variable_get(name)
+            fn.required_positionals << Types::Function::Param.new(name: nil, type: parse_object(value))
+          when :opt
+            value = bind.local_variable_get(name)
+            fn.optional_positionals << Types::Function::Param.new(name: nil, type: parse_object(value))
+          when :rest
+            type = if name.nil? || name == :*
+                     type_untyped
+                   else
+                     value = bind.local_variable_get(name)
+                     parse_classes(value.map { |v| obj_to_class(v) }.uniq)
+                   end
+            fn = fn.update(rest_positionals: Types::Function::Param.new(name: nil, type:)) # rubocop:disable Style/RedundantSelfAssignment
+          when :keyreq
+            value = bind.local_variable_get(name)
+            fn.required_keywords[name] = Types::Function::Param.new(name: nil, type: parse_object(value))
+          when :key
+            value = bind.local_variable_get(name)
+            fn.optional_keywords[name] = Types::Function::Param.new(name: nil, type: parse_object(value))
+          when :keyrest
+            type = if name.nil? || name == :**
+                     type_untyped
+                   else
+                     value = bind.local_variable_get(name)
+                     parse_classes(value.values.map { |v| obj_to_class(v) }.uniq)
+                   end
+            fn = fn.update(rest_keywords: Types::Function::Param.new(name: nil, type:)) # rubocop:disable Style/RedundantSelfAssignment
+          when :block
+            # TODO: support block argument
+            next
+          end
+        end
+
+        MethodType.new(
+          type_params: [],
+          type: fn,
+          block: nil,
+          location: nil
+        )
+      end
+
+      # @rbs (Array[untyped]) -> Types::t
+      def parse_classes(classes)
+        types = classes.filter_map { |klass| parse_class(klass) unless klass == NilClass }.uniq
+        return type_nil if types.empty?
+
+        type = types.one? ? types.first : Types::Union.new(types:, location: nil) #: Types::t
+        if classes.include?(NilClass)
+          Types::Optional.new(type:, location: nil)
+        else
+          type
+        end
+      end
+
+      # @rbs (untyped) -> Types::t
+      def parse_class(klass) # rubocop:disable Metrics/MethodLength
+        class_name = UNBOUND_NAME_METHOD.bind_call(klass)
+        if [TrueClass, FalseClass].include?(klass)
+          type_bool
+        elsif klass == NilClass
+          type_nil
+        elsif klass == Object || class_name.nil?
+          type_untyped
+        else
+          size = GENERICS_SIZE[klass].to_i
+          args = Array.new(size) { type_untyped }
+          Types::ClassInstance.new(name: TypeName.parse(class_name), args:, location: nil)
+        end
+      end
+
+      # @rbs (BasicObject) -> Types::t
+      def parse_object(object)
+        klass = obj_to_class(object)
+        parse_class(klass)
+      end
+
+      # @rbs (BasicObject) -> Class
+      def obj_to_class(obj)
+        UNBOUND_CLASS_METHOD.bind_call(obj)
+      end
+    end
+  end
+end

data/lib/rbs/trace/cli/inline.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module RBS
+  class Trace
+    class CLI
+      class Inline
+        BANNER = <<~USAGE
+          Usage: rbs-trace inline --sig-dir=DIR --rb-dir=DIR
+
+          Insert RBS inline comments from RBS files.
+
+          Examples:
+            # Insert inline comments to `app/**/*.rb`.
+            $ rbs-trace inline --sig-dir=sig --rb-dir=app
+
+            # Generate RBS files with rbs-inline.
+            $ rbs-inline --output --opt-out app
+
+            # Remove method definitions that have been migrated to inline comments.
+            $ rbs subtract --write sig sig/generated/
+
+          Options:
+        USAGE
+
+        # @rbs (Array[String]) -> void
+        def run(args) # rubocop:disable Metrics
+          sig_dir = Pathname.pwd.join("sig").to_s
+          rb_dirs = [] #: Array[String]
+
+          opts = OptionParser.new(BANNER)
+          opts.on("--sig-dir DIR") { |dir| sig_dir = dir }
+          opts.on("--rb-dir DIR") { |dir| rb_dirs << dir }
+          opts.parse!(args)
+
+          if rb_dirs.empty?
+            puts opts.help
+          else
+            env = load_env(sig_dir) # steep:ignore ArgumentTypeMismatch
+            decls = env.class_decls.transform_values { |v| v.primary.decl }
+
+            rb_files = rb_dirs.flat_map { |rb_dir| Dir.glob("#{rb_dir}/**/*.rb") }
+            rb_files.each do |path|
+              file = File.new(path, decls)
+              file.rewrite
+            end
+          end
+        end
+
+        private
+
+        # @rbs (String) -> Environment
+        def load_env(dir)
+          Environment.new.tap do |env|
+            loader = EnvironmentLoader.new(core_root: nil)
+            loader.add(path: Pathname(dir))
+            loader.load(env:)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rbs/trace/cli/merge.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module RBS
+  class Trace
+    class CLI
+      class Merge
+        BANNER = <<~USAGE
+          Usage: rbs-trace merge --sig-dir=DIR
+
+          Merge multiple RBS files into one.
+
+          Examples:
+            # Merge RBS files in `tmp/sig-1/` and `tmp/sig-2/`.
+            $ rbs-trace merge --sig-dir=tmp/sig-1 --sig-dir=tmp/sig-2
+
+            # Or you can specify a glob pattern.
+            $ rbs-trace merge --sig-dir=tmp/sig-*
+
+          Options:
+        USAGE
+
+        # @rbs (Array[String]) -> void
+        def run(args) # rubocop:disable Metrics
+          sig_dirs = [] #: Array[String]
+
+          opts = OptionParser.new(BANNER)
+          opts.on("--sig-dir DIR") { |dir| sig_dirs << dir }
+          opts.parse!(args)
+
+          if sig_dirs.empty?
+            puts opts.help
+          else
+            envs = sig_dirs.flat_map { |sig_dir| Dir.glob(sig_dir) }
+                           .map { |dir| load_env(dir) }
+            env = merge_envs(envs)
+
+            out = StringIO.new
+            writer = Writer.new(out:)
+            writer.write(env.declarations)
+
+            puts out.string
+          end
+        end
+
+        # @rbs (Array[Environment]) -> Environment
+        def merge_envs(others) # rubocop:disable Metrics
+          Environment.new.tap do |env|
+            others.each do |other|
+              other.declarations.each do |decl|
+                next unless decl.is_a?(AST::Declarations::Class) || decl.is_a?(AST::Declarations::Module)
+
+                entry = env.module_class_entry(decl.name.absolute!)
+
+                if entry.is_a?(Environment::MultiEntry)
+                  decl.members.each { |member| merge(entry.primary.decl, member) }
+                else
+                  env << decl
+                end
+              end
+            end
+          end
+        end
+
+        private
+
+        # @rbs (String) -> Environment
+        def load_env(dir)
+          Environment.new.tap do |env|
+            loader = EnvironmentLoader.new(core_root: nil)
+            loader.add(path: Pathname(dir))
+            loader.load(env:)
+          end
+        end
+
+        def merge(decl, member) # rubocop:disable Metrics
+          case member
+          when AST::Declarations::Class, AST::Declarations::Module
+            d = decl.members.find { |m| m.is_a?(member.class) && m.name == member.name }
+
+            if d
+              member.members.each { |m| merge(d, m) }
+            else
+              decl.members << member
+            end
+          when AST::Members::MethodDefinition
+            found = decl.members.find { |m| m.is_a?(member.class) && m.name == member.name && m.kind == member.kind }
+
+            if found
+              (member.overloads - found.overloads).each do |overload|
+                found.overloads << overload
+              end
+            else
+              decl.members << member
+            end
+          else
+            decl.members << member unless decl.members.include?(member)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rbs/trace/cli.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module RBS
+  class Trace
+    class CLI
+      BANNER = <<~USAGE
+        Usage: rbs-trace <command> [<args>]
+
+        Available commands: inline, merge
+      USAGE
+
+      # @rbs (Array[String]) -> void
+      def run(args = ARGV)
+        opts = OptionParser.new(BANNER)
+        opts.version = RBS::Trace::VERSION
+        opts.order!(args)
+        command = args.shift&.to_sym
+
+        klass = command_class(command)
+        if klass
+          klass.new.run(args)
+        else
+          puts opts.help
+        end
+      end
+
+      private
+
+      # @rbs (Symbol?) -> (singleton(Inline) | singleton(Merge))?
+      def command_class(command)
+        case command
+        when :inline
+          Inline
+        when :merge
+          Merge
+        end
+      end
+    end
+  end
+end