yard2rbs 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 74d0fab907be0a8229347fbda564913a08a6688b3b1c76db58ab98e52a783c3b
+  data.tar.gz: 1e51981642df3c3ee35cfd8a0e8c9651d6c03db6fff51bb7fd8d995f96101b13
+SHA512:
+  metadata.gz: c29df8ed7704ff31f8a7640a52f3f50e02ccf654e0d999c25d3c228b162e9488c1abf598e71d63f39ec4c240ee1a2cd685dcd9a2b898d2d6c35b665035865d6c
+  data.tar.gz: 20c59a4b6462c4d14636587d7426faf377b2931ccb6c9ce7ae6eebaf5725ed58cc5dcc4859c6be00b46e6afd70e8efeec1c233bdba648e0b47a4d12d70b74bbb

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Kieran Pilkington
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,37 @@
+# Yard2Rbs
+
+Convert YARD documentation in Ruby files into RBS type definitions.
+
+Utilizes `prism` Ruby parser to parse files and validates resulting RBS files.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add yard2rbs
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install yard2rbs
+
+## Usage
+
+Convert all files:
+
+```
+yard2rbs **/*.rb
+```
+
+Convert specific files:
+
+```
+yard2rbs app/models/user.rb app/services/user_creator.rb
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/KieranP/yard2rbs.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/exe/yard2rbs

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "yard2rbs"
+
+Yard2rbs.convert(ARGV)

data/lib/yard2rbs/converter.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require "prism"
+
+# https://ruby.github.io/prism/rb/index.html
+# https://github.com/ruby/rbs/blob/master/docs/syntax.md
+# https://github.com/ruby/rbs/blob/master/lib/rbs/prototype/rb.rb
+
+module Yard2rbs
+  class Converter
+    # @param input_path [String]
+    # @return [void]
+    def initialize(input_path)
+      @parse_result = Prism.parse_file(input_path)
+      @parse_result.attach_comments!
+      @output = []
+    end
+
+    # @return [String]
+    def convert
+      @_indent_level = 0
+      # puts @parse_result.value.inspect
+      process(@parse_result.value)
+      output = @output.join("\n")
+      validate(output)
+      output
+    end
+
+    private
+
+    # @param node [Prism::Node]
+    # @return [true]
+    def process(node)
+      case node
+      when Array
+        node.each do |v|
+          process(v)
+        end
+
+      when Prism::ClassNode
+        if node.superclass
+          output("class #{node.constant_path.name} < #{node.superclass.name}")
+        else
+          output("class #{node.constant_path.name}")
+        end
+        @_indent_level += 1
+        process(node.compact_child_nodes)
+        @_indent_level -= 1
+        output("end")
+
+      when Prism::SingletonClassNode
+        @_within_singleton = true
+        process(node.compact_child_nodes)
+        @_within_singleton = false
+
+      when Prism::ModuleNode
+        output("module #{node.constant_path.name}")
+        @_indent_level += 1
+        process(node.compact_child_nodes)
+        @_indent_level -= 1
+        output("end")
+
+      when Prism::ConstantWriteNode
+        types = parse_comments(node)
+        type = format_types(types[:returns])
+        output("#{node.name}: #{type}")
+
+      when Prism::ClassVariableWriteNode
+        output("#{node.name}: untyped")
+
+      when Prism::InstanceVariableWriteNode
+        output("self.#{node.name}: untyped")
+
+      when Prism::DefNode
+        visibility = @_visibility_node&.name
+        receiver = "self." if self?(node)
+
+        types = parse_comments(@_visibility_node || node)
+        params = []
+        block = nil
+
+        if node.parameters
+          if node.parameters.requireds
+            node.parameters.requireds.each do |arg|
+              type = format_types(types[:params][arg.name.to_s])
+              params << "#{type} #{arg.name}"
+            end
+          end
+
+          if node.parameters.optionals
+            node.parameters.optionals.each do |arg|
+              type = format_types(types[:params][arg.name.to_s])
+              params << "?#{type} #{arg.name}"
+            end
+          end
+
+          if arg = node.parameters.rest
+            type = format_types(types[:params][arg.name.to_s])
+            params << "*#{type} #{arg.name}"
+          end
+
+          if node.parameters.keywords
+            node.parameters.keywords.each do |arg|
+              type = format_types(types[:params][arg.name.to_s])
+              if arg.is_a?(Prism::OptionalKeywordParameterNode)
+                params << "?#{arg.name}: #{type}"
+              else
+                params << "#{arg.name}: #{type}"
+              end
+            end
+          end
+
+          if arg = node.parameters.keyword_rest
+            type = format_types(types[:params][arg.name.to_s])
+            params << "**#{type} #{arg.name}"
+          end
+
+          if arg = node.parameters.block
+            block = "{ (?) -> untyped }"
+          end
+        end
+
+        return_type = format_types(types[:returns])
+
+        output([
+          visibility,
+          "def",
+          "#{receiver}#{node.name}:",
+          "(#{params.join(", ")})",
+          block,
+          "-> #{return_type}"
+        ].compact.join(' '))
+
+      when Prism::CallNode
+        case node.name
+        when :public, :private
+          if node.arguments
+            @_visibility_node = node
+            node.arguments.arguments.each do |inner_node|
+              process(inner_node)
+            end
+            @_visibility_node = nil
+          else
+            receiver = "self." if self?(node)
+            output("#{receiver}#{node.name}")
+          end
+
+        when :attr_accessor, :attr_reader, :attr_writer
+          if node.arguments
+            receiver = "self." if self?(node)
+            node.arguments.arguments.each do |arg|
+              output([
+                "#{receiver}#{node.name}",
+                "#{arg.unescaped}: untyped"
+              ].compact.join(' '))
+            end
+          end
+
+        when :extend, :prepend, :include
+          if node.arguments
+            receiver = "self." if self?(node)
+            node.arguments.arguments.each do |arg|
+              output("#{receiver}#{node.name} #{arg.name}")
+            end
+          end
+
+        when :alias_method
+          if node.arguments
+            args = node.arguments.arguments
+            new_name = args.first.unescaped
+            old_name = args.last.unescaped
+            output("#{receiver}alias #{new_name} #{old_name}")
+          end
+
+        else
+          process(node.compact_child_nodes)
+        end
+
+      when Prism::AliasMethodNode
+        new_name = node.new_name.unescaped
+        old_name = node.old_name.unescaped
+        output("alias #{new_name} #{old_name}")
+
+      else
+        process(node.compact_child_nodes)
+      end
+
+      true
+    end
+
+    # @param output [String]
+    # @return [true]
+    def validate(output)
+      RBS::Parser.parse_signature(output)
+      true
+    end
+
+    # @param str [String]
+    # @return [String]
+    def output(str)
+      @output << ("  " * @_indent_level) + str
+    end
+
+    # @param node [Prism::Node]
+    # @return [Boolean]
+    def self?(node)
+      node.receiver&.type == :self_node ||
+        @_within_singleton
+    end
+
+    # @param node [Prism::Node]
+    # @return [Hash]
+    def parse_comments(node)
+      params = {}
+      returns = []
+
+      comments = node.location.comments
+      comments&.each do |comment|
+        line = comment.slice
+
+        case line
+        when /@param/
+          if matches = line.match(/# @param ([^\s]+) \[([^\]]+)\].*/)
+            types = matches[2].split(',').map(&:strip)
+            params[matches[1]] = convert_types(types)
+          end
+        when /@return/
+          if matches = line.match(/# @return \[([^\]]+)\].*/)
+            types = matches[1].split(',').map(&:strip)
+            returns += convert_types(types)
+          end
+        end
+      end
+
+      {
+        params: params,
+        returns: returns,
+      }
+    end
+
+    # @param types [String]
+    # @return [Array<String>]
+    def convert_types(types)
+      types.map do |type|
+        type.
+          gsub(/Array\<([^>]+)\>/, 'Array[\1]').
+          gsub(/Hash\<([^>]+),\s*([^>]+)\>/, 'Hash[\1,\2]')
+      end
+    end
+
+    # @param types [Array<String>]
+    # @return [String]
+    def format_types(types)
+      return 'untyped' if !types || types.size == 0
+
+      nilable = true if types.delete('nil')
+
+      if types.size > 1
+        "(#{types.join(' | ')})#{'?' if nilable}"
+      else
+        "#{types.first}#{'?' if nilable}"
+      end
+    end
+  end
+end

data/lib/yard2rbs/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Yard2rbs
+  # @return [String]
+  VERSION = "0.0.1"
+end

data/lib/yard2rbs.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "yard2rbs/converter"
+require_relative "yard2rbs/version"
+
+require "rbs"
+
+module Yard2rbs
+  class << self
+    # @param file_paths [Array<String>]
+    # @return [Boolean]
+    def convert(file_paths)
+      # TODO: Clear out rbs/ directory
+
+      file_paths.each do |file_path|
+        output = Converter.new(file_path).convert
+        next if output.empty?
+
+        input_dirname = File.dirname(file_path)
+        input_filename = File.basename(file_path, ".*")
+
+        output_dirname = File.join("sig", input_dirname)
+        output_filename = "#{input_filename}.rbs"
+        output_path = File.join(output_dirname, output_filename)
+
+        FileUtils.mkdir_p(output_dirname)
+        File.open(output_path, 'w+') do |file|
+          file.puts(output)
+        end
+      end
+
+      true
+    end
+  end
+end

data/sig/lib/yard2rbs/converter.rbs

@@ -0,0 +1,14 @@
+module Yard2rbs
+  class Converter
+    def initialize: (String input_path) -> void
+    def convert: () -> String
+    private
+    def process: (Prism::Node node) -> true
+    def validate: (String output) -> true
+    def output: (String str) -> String
+    def self?: (Prism::Node node) -> Boolean
+    def parse_comments: (Prism::Node node) -> Hash
+    def convert_types: (String types) -> Array[String]
+    def format_types: (Array[String] types) -> String
+  end
+end

data/sig/lib/yard2rbs/version.rbs

@@ -0,0 +1,3 @@
+module Yard2rbs
+  VERSION: String
+end

data/sig/lib/yard2rbs.rbs

@@ -0,0 +1,3 @@
+module Yard2rbs
+  def self.convert: (Array[String] file_paths) -> Boolean
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: yard2rbs
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Kieran Pilkington
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-06-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.30.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.30.0
+- !ruby/object:Gem::Dependency
+  name: rbs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.5.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.5.1
+description:
+email:
+- kieran776@gmail.com
+executables:
+- yard2rbs
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/yard2rbs
+- lib/yard2rbs.rb
+- lib/yard2rbs/converter.rb
+- lib/yard2rbs/version.rb
+- sig/lib/yard2rbs.rbs
+- sig/lib/yard2rbs/converter.rbs
+- sig/lib/yard2rbs/version.rbs
+homepage:
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: Convert YARD documentation into RBS files
+test_files: []