rbs-trace 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f0c689aa7e7519cd2ba4338c195c39dad1baa4022c96ed79b091b7e0051ba4a
-  data.tar.gz: 22b18905f9ae5b4a4cc3a9714a8db2b0289d822730752942dfa2aa1160864ed8
+  metadata.gz: 2e7d9ae59c5c4d3427c486422dcda9158bb65b1d5054d0ab5713a9714de9f39c
+  data.tar.gz: fc377a935ef972ac2e153d40f336154c03cb1e42b88dc732132f2e71bba83047
 SHA512:
-  metadata.gz: 83ba38515e5363c85fb866709e063de85211e4c5b61dc9ff08277aa7e805f7fa92a7e9d515cf6b6786980b6f791f8f04517fc447971c62f85fa3d2189da2dbdb
-  data.tar.gz: 91eb1069c5e6fe40d6fcda2f8f0ac07bf63e34dc59492322e102335f294ab6cd52cd5b3b7a1ad6574e2eb04c2630951305d8ab910ff2c85e80195dcc33fef11e
+  metadata.gz: e3ff05d28fbef44e66500377dd38e74a0a3890da197d00bbf61b461358d404fef1933d43e30655a5dffce3850f1a71b4d535b88db8e209d2d1100ba7c1f502e9
+  data.tar.gz: 446d6c0d49e72fae943708bc146bf80365cd107bac3d9c509950a0184611f19982dc244f0398964ff50d4d462756a3004ce73e5d5d0488a1ae9e41257555a447

data/.rubocop.yml

@@ -16,7 +16,7 @@ Style/Documentation:
   Enabled: false
 
 RSpec/ExampleLength:
-  Max: 15
+  Max: 50
 
 Naming/MethodParameterName:
   Enabled: false
@@ -25,8 +25,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,35 @@
 ## [Unreleased]
 
+## [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
+
 ## [0.3.1] - 2024-10-19
 
 - fix: Fix the number of types specified in generics

data/README.md

@@ -1,6 +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
 
@@ -33,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
@@ -76,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
 ```
 
@@ -114,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`.
@@ -139,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"
@@ -19,9 +26,4 @@ task :steep do
   sh "steep check"
 end
 
-default = if RUBY_VERSION.start_with?("3.3")
-            %i[spec rubocop rbs_inline steep]
-          else
-            %i[spec rubocop]
-          end
-task(default:)
+task(default: %i[spec rubocop rbs_inline 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,124 @@
+# frozen_string_literal: true
+
+module RBS
+  class Trace
+    class Builder
+      include Helpers
+
+      GENERICS_SIZE = {
+        Array => 1,
+        Range => 1,
+        Hash => 2
+      }.freeze
+      private_constant :GENERICS_SIZE
+
+      # @rbs (bind: Binding, parameters: Array[__todo__], void: bool) -> void
+      def method_call(bind:, parameters:, void:)
+        method_type = parse_parameters(bind, parameters)
+        return_type = type_void if void
+
+        stack_traces << [method_type, return_type]
+      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
+        if [TrueClass, FalseClass].include?(klass)
+          type_bool
+        elsif klass == NilClass
+          type_nil
+        elsif klass == Object || klass.name.nil?
+          type_untyped
+        else
+          size = GENERICS_SIZE[klass].to_i
+          args = Array.new(size) { type_untyped }
+          Types::ClassInstance.new(name: TypeName.parse(klass.name), args:, location: nil)
+        end
+      end
+
+      # @rbs (BasicObject) -> Types::t
+      def parse_object(object)
+        klass = obj_to_class(object)
+        parse_class(klass)
+      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

data/lib/rbs/trace/file.rb

@@ -1,29 +1,43 @@
 # frozen_string_literal: true
 
+require "stringio"
+
 module RBS
-  module Trace
+  class Trace
     class File
-      # @rbs (String) -> void
-      def initialize(path)
+      include Helpers
+
+      # @rbs (String, ?Hash[TypeName, AST::Declarations::t]) -> void
+      def initialize(path, decls = {})
         @path = path
+        @decls = decls
+        @members = {} #: Hash[TypeName, AST::Declarations::t]
       end
 
-      # @rbs () -> Hash[String, Definition]
-      def definitions
-        @definitions ||= {}
+      # @rbs (untyped, Class, Symbol) -> AST::Members::MethodDefinition?
+      def find_or_new_method_definition(object, defined_class, name)
+        klass = defined_class.singleton_class? ? object : defined_class
+        receiver_decl = find_or_new_receiver_decl(klass)
+        return unless receiver_decl
+
+        kind = defined_class.singleton_class? ? :singleton : :instance
+        key = [receiver_decl.name, name, kind]
+        @members[key] ||= new_method_definition(name:, kind:).tap do |member| # steep:ignore ArgumentTypeMismatch
+          receiver_decl.members << member
+        end
       end
 
       # @rbs () -> String
       def with_rbs
-        lines = ::File.readlines(@path)
-        reverse_definitions.each do |d|
-          next if skip_insert?(lines, d)
+        result = Prism.parse_file(@path)
+        comments = {} #: Hash[Integer, String]
+        result.value.accept(InlineCommentVisitor.new(@decls, comments))
 
-          current = d.lineno - 1
-          indent = lines[current]&.index("def")
-          next unless indent
+        lines = result.source.source.lines
+        comments.keys.sort.reverse_each do |i|
+          next if skip_insert?(lines, i)
 
-          lines.insert(current, d.rbs_comment(indent))
+          lines.insert(i, comments[i])
         end
         lines.join
       end
@@ -33,18 +47,53 @@ module RBS
         ::File.write(@path, with_rbs)
       end
 
+      # @rbs () -> String
+      def to_rbs
+        out = StringIO.new
+        writer = Writer.new(out:)
+        writer.write(@decls.values)
+
+        out.string
+      end
+
+      # @rbs (String) -> void
+      def save_rbs(out_dir)
+        rbs_path = calc_rbs_path(out_dir)
+
+        rbs_path.parent.mkpath unless rbs_path.parent.exist?
+        rbs_path.write(to_rbs)
+      end
+
       private
 
-      # @rbs (Array[String], Definition) -> boolish
-      def skip_insert?(lines, definition)
-        prev = definition.lineno - 2
+      # @rbs (Array[String], Integer) -> boolish
+      def skip_insert?(lines, current)
+        prev = current - 1
 
-        definition.decls.empty? || lines[prev]&.include?("# @rbs")
+        lines[prev]&.include?("# @rbs") ||
+          lines[prev]&.include?("#:") ||
+          lines[current]&.include?("#:")
       end
 
-      # @rbs () -> Enumerator[Definition, void]
-      def reverse_definitions
-        @definitions.values.sort_by { |d| -d.lineno }
+      # @rbs (Class | Module) -> (AST::Declarations::Class | AST::Declarations::Module)?
+      def find_or_new_receiver_decl(klass)
+        return unless klass.name
+        return if klass.name.is_a?(Symbol)
+
+        # Remove anonymous class names
+        class_name = klass.name.to_s.split("::").grep_v(/^#/).join("::")
+        name = TypeName.parse(class_name)
+
+        @decls[name.absolute!] ||= klass.is_a?(Class) ? new_class_decl(name:) : new_module_decl(name:)
+      end
+
+      # @rbs (String) -> Pathname
+      def calc_rbs_path(out_dir)
+        rb_path = Pathname(@path).sub(Pathname.pwd.to_s, "")
+        rb_path = rb_path.relative_path_from("/") if rb_path.absolute?
+        rbs_path = rb_path.sub_ext(".rbs")
+
+        Pathname(out_dir) + rbs_path
       end
     end
   end