yarbs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 14192c2d967c20c40a4ed4e9d24d810b6bcaf8fa957261c27d904301f5d6e980
+  data.tar.gz: 7a2bc9f86103deaf360be3c6fabcd5895d6bca0280ab1f0c95a426921852448f
+SHA512:
+  metadata.gz: 50961f4fa46908f161a8748602fa2a282cbb00a018a44d7f701b96043e7ceb1332359526318359efd7d86cdce8fa944aac2a442d7daedd70a7caa5eb0e24b74e
+  data.tar.gz: 5f59a649d92e618223e4b60bd23d05b7e2a7f68a08818a70083bf17b5981e2e11cf2bc2a55f9821528fc1359c36da04d976cb4b1db021209b79d98dc119e16d3

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 tobidelius
+
+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,131 @@
+# Yarbs
+
+[![Ruby](https://github.com/tobidelius/yarbs/actions/workflows/main.yml/badge.svg)](https://github.com/tobidelius/yarbs/actions/workflows/main.yml)
+
+*This is still experimental.*
+
+---
+
+Generate [RBS](https://github.com/ruby/rbs) type signatures from your
+existing [YARD](https://yardoc.org) documentation.
+
+Most Ruby projects that adopt RBS end up writing types twice: once as
+`@param`/`@return` comments for humans, and again as `.rbs` files for the
+type checker. yarbs closes that gap. It uses `rbs prototype rb` to work out
+the real *structure* of your code (arity, visibility, `attr_*`, mixins,
+inheritance — all parsed straight from your source, not guessed), then
+reads the YARD docs you've already written to fill in the *types*, and
+writes the result to `sig/`.
+
+```ruby
+class Greeter
+  # @param name [String] the person's name
+  # @param count [Integer, nil] how many times to greet
+  # @return [Boolean] whether it worked
+  def greet(name, count: nil)
+    true
+  end
+end
+```
+
+```bash
+$ yarbs "lib/**/*.rb"
+wrote sig/greeter.rbs
+```
+
+```rbs
+class Greeter
+  def greet: (String name, ?count: Integer | nil) -> bool
+end
+```
+
+No YARD tag for a given parameter or return value? It's just left `untyped`
+— nothing breaks, and everything else in the signature still gets its real
+type.
+
+## Installation
+
+Install the gem and add it to the application's Gemfile by executing:
+
+```bash
+bundle add yarbs
+```
+
+If bundler is not being used to manage dependencies, install the gem by
+executing:
+
+```bash
+gem install yarbs
+```
+
+## Usage
+
+Point yarbs at your source files with one or more glob patterns; it writes
+one `.rbs` file per source file into `sig/` (or `-o DIR` to choose a
+different output directory), mirroring the source layout with a leading
+`lib/`/`app/` stripped:
+
+```bash
+yarbs "lib/**/*.rb" "app/**/*.rb"
+```
+
+Other flags:
+
+- `-o`, `--output DIR` — write into `DIR` instead of `sig/`
+- `-w`, `--watch` — regenerate automatically whenever a matched file changes
+  (built on [listen](https://github.com/guard/listen)); handy to run
+  alongside your editor while developing
+- `-s`, `--strict` — raise instead of silently falling back to `untyped`
+  when a YARD type can't be converted or a file has invalid syntax (not
+  combinable with `--watch`, since a strict watcher would crash on every
+  keystroke mid-edit)
+
+It's also available as a plain Ruby API:
+
+```ruby
+require "yarbs"
+
+Yarbs.generate(["lib/**/*.rb"], output_dir: "sig", strict: true)
+```
+
+### Docs
+
+For the full picture of what yarbs understands and how to document it —
+worked examples generated by actually running the tool, not hand-written —
+see:
+
+- [docs/param.md](docs/param.md) — `@param`, including `*args`, `**kwargs`,
+  and `@option` (typed as an RBS record)
+- [docs/return.md](docs/return.md) — `@return`, including `void` and the
+  `#initialize` special case
+- [docs/blocks.md](docs/blocks.md) — `yield`/`&block`
+  (`@yieldparam`/`@yieldreturn`), and typing a `Proc`/lambda parameter
+- [docs/classes.md](docs/classes.md) — classes, modules, nesting,
+  inheritance, mixins, `attr_*`, constants, and visibility
+
+## Development
+
+After checking out the repo, run `bundle install`, then
+`bundle exec rbs collection install` to fetch the RBS signatures Steep needs
+for yarbs' own dependencies. From there:
+
+- `bundle exec rake` runs the full check: tests (`rake test`), lint
+  (`rake standard`), and type checking (`rake steep`)
+- `bundle exec exe/yarbs "lib/**/*.rb" -o sig` regenerates yarbs' own `sig/`
+  from its own docs (it's self-hosting)
+
+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).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/tobidelius/yarbs.
+
+## 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,14 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "standard/rake"
+
+task :steep do
+  sh "bundle exec steep check"
+end
+
+task default: %i[test standard steep]

data/exe/yarbs

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "yarbs"
+
+Yarbs::CLI.run(ARGV)

data/lib/yarbs/annotator.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require "rbs"
+require "yard"
+
+module Yarbs
+  # Walks an +RBS::AST::Declarations+ tree produced by {PrototypeBuilder} and
+  # fills in its +untyped+ placeholders with types read from the matching
+  # YARD documentation (already loaded into +YARD::Registry+).
+  class Annotator
+    # Fills in the +untyped+ placeholders in a decls tree using YARD documentation.
+    #
+    # @param decls [Array<RBS::AST::Declarations::t>]
+    # @param strict [Boolean] raise instead of falling back to +untyped+
+    #   when a YARD type can't be converted
+    # @return [Array<RBS::AST::Declarations::t>] a new tree with YARD-derived types merged in
+    def self.annotate(decls, strict: false)
+      new(strict).visit_all(decls, [])
+    end
+
+    def initialize(strict)
+      @strict = strict
+    end
+
+    def visit_all(decls, namespace)
+      decls.map { |decl| visit(decl, namespace) }
+    end
+
+    def visit(decl, namespace)
+      case decl
+      when RBS::AST::Declarations::Class, RBS::AST::Declarations::Module
+        inner_namespace = namespace + [decl.name.to_s]
+        decl.update(members: visit_all(decl.members, inner_namespace))
+      when RBS::AST::Declarations::Constant
+        annotate_constant(decl, namespace)
+      when RBS::AST::Members::MethodDefinition
+        annotate_method(decl, namespace)
+      when RBS::AST::Members::AttrReader, RBS::AST::Members::AttrWriter, RBS::AST::Members::AttrAccessor
+        annotate_attribute(decl, namespace)
+      else
+        decl
+      end
+    end
+
+    private
+
+    def annotate_constant(decl, namespace)
+      yard_object = YARD::Registry.at("#{namespace.join("::")}::#{decl.name}")
+      types = return_types_of(yard_object)
+      return decl if types.empty?
+
+      RBS::AST::Declarations::Constant.new(
+        name: decl.name,
+        type: convert(types),
+        location: decl.location,
+        comment: decl.comment,
+        annotations: decl.annotations
+      )
+    end
+
+    def annotate_method(member, namespace)
+      base = namespace.join("::")
+      yard_method = YARD::Registry.at("#{base}##{member.name}") || YARD::Registry.at("#{base}.#{member.name}")
+      return member unless yard_method
+
+      overloads = member.overloads.map { |overload| annotate_overload(overload, yard_method) }
+      member.update(overloads: overloads)
+    end
+
+    def annotate_attribute(member, namespace)
+      sep = (member.kind == :singleton) ? "." : "#"
+      # attr_writer has no reader, so YARD only ever registers the `name=`
+      # method (attr_accessor has both, but they share one @return tag, so
+      # the reader's plain path works fine for it too).
+      suffix = member.is_a?(RBS::AST::Members::AttrWriter) ? "=" : ""
+      yard_attr = YARD::Registry.at("#{namespace.join("::")}#{sep}#{member.name}#{suffix}")
+      types = return_types_of(yard_attr)
+      return member if types.empty?
+
+      member.update(type: convert(types))
+    end
+
+    def annotate_overload(overload, yard_method)
+      method_type = overload.method_type
+      new_type = method_type.update(
+        type: annotate_function(method_type.type, yard_method),
+        block: method_type.block && annotate_block(method_type.block, yard_method)
+      )
+      overload.update(method_type: new_type)
+    end
+
+    def annotate_function(function, yard_method)
+      params = param_types_by_name(yard_method)
+      options = option_records_by_name(yard_method)
+
+      # @option only substitutes a record type onto a plain (non-rest) Hash
+      # parameter -- for *args/**kwargs, RBS's rest type describes a single
+      # element/value, and there's no way to express "these specific
+      # keyword names have these specific types" through it, so @option is
+      # left to apply to the base @param type there instead (see param.md).
+      RBS::Types::Function.new(
+        required_positionals: function.required_positionals.map { |param| annotate_param(param, params, options) },
+        optional_positionals: function.optional_positionals.map { |param| annotate_param(param, params, options) },
+        rest_positionals: annotate_param(function.rest_positionals, params, {}, unwrap: :array),
+        trailing_positionals: function.trailing_positionals.map { |param| annotate_param(param, params, options) },
+        required_keywords: annotate_keywords(function.required_keywords, params, options),
+        optional_keywords: annotate_keywords(function.optional_keywords, params, options),
+        rest_keywords: annotate_param(function.rest_keywords, params, {}, unwrap: :hash),
+        return_type: return_type_for(function, yard_method),
+        forwarding: function.forwarding
+      )
+    end
+
+    def annotate_block(block, yard_method)
+      yield_params = yard_method.tags(:yieldparam)
+      yieldreturn = yard_method.tag(:yieldreturn)
+      new_return_type = ->(current) { yieldreturn&.types&.any? ? convert(yieldreturn.types) : current }
+
+      # `rbs prototype rb` can only infer a block's arity from literal
+      # `yield x, y` call sites in the method body. A block that's only
+      # ever `.call`ed (e.g. `def foo(&block); block.call(x); end`) gives
+      # it nothing to go on, so it produces an `UntypedFunction` (`(?) ->
+      # untyped`) instead of a full `Function` -- handle both.
+      new_function = case (function = block.type)
+      when RBS::Types::Function
+        annotate_block_function(function, yield_params, new_return_type)
+      when RBS::Types::UntypedFunction
+        annotate_untyped_block_function(function, yield_params, new_return_type)
+      else
+        function
+      end
+
+      RBS::Types::Block.new(type: new_function, required: block.required, self_type: block.self_type)
+    end
+
+    def annotate_block_function(function, yield_params, new_return_type)
+      new_required_positionals = function.required_positionals.each_with_index.map do |param, index|
+        tag = yield_params[index]
+        next param unless tag&.types
+
+        RBS::Types::Function::Param.new(name: param.name || safe_symbol(tag.name), type: convert(tag.types))
+      end
+
+      RBS::Types::Function.new(
+        required_positionals: new_required_positionals,
+        optional_positionals: function.optional_positionals,
+        rest_positionals: function.rest_positionals,
+        trailing_positionals: function.trailing_positionals,
+        required_keywords: function.required_keywords,
+        optional_keywords: function.optional_keywords,
+        rest_keywords: function.rest_keywords,
+        return_type: new_return_type.call(function.return_type),
+        forwarding: function.forwarding
+      )
+    end
+
+    # There's no arity to preserve here, but if `@yieldparam` tags exist we
+    # at least know the documented shape, so build a full positional-only
+    # `Function` from them instead of leaving the block's params untyped.
+    def annotate_untyped_block_function(function, yield_params, new_return_type)
+      return function.map_type { new_return_type.call(function.return_type) } if yield_params.empty?
+
+      positionals = yield_params.map do |tag|
+        RBS::Types::Function::Param.new(name: safe_symbol(tag.name), type: convert(tag.types))
+      end
+
+      RBS::Types::Function.new(
+        required_positionals: positionals,
+        optional_positionals: [],
+        rest_positionals: nil,
+        trailing_positionals: [],
+        required_keywords: {},
+        optional_keywords: {},
+        rest_keywords: nil,
+        return_type: new_return_type.call(function.return_type),
+        forwarding: nil
+      )
+    end
+
+    # Applies the type documented for a single structural parameter.
+    #
+    # @param unwrap [Symbol, nil] for a rest parameter (`*args`/`**kwargs`),
+    #   YARD conventionally documents the *collected* type (`Array<String>`,
+    #   `Hash{Symbol => String}`), but RBS's `*`/`**` types describe a single
+    #   element instead, so one layer of `Array`/`Hash` is stripped back off.
+    def annotate_param(param, params, options, unwrap: nil)
+      return param unless param&.name
+
+      name = param.name.to_s
+      return param.map_type { options[name] } if options[name]
+
+      types = params[name]
+      types ? param.map_type { unwrap_rest_type(convert(types), unwrap) } : param
+    end
+
+    def unwrap_rest_type(type, unwrap)
+      return type unless type.is_a?(RBS::Types::ClassInstance)
+
+      case unwrap
+      when :array
+        type.args.first if type.name.to_s == "Array" && type.args.size == 1
+      when :hash
+        type.args.last if type.name.to_s == "Hash" && type.args.size == 2
+      end || type
+    end
+
+    def annotate_keywords(keywords, params, options)
+      keywords.each_with_object({}) do |(key, param), result|
+        name = key.to_s
+
+        if options[name]
+          result[key] = param.map_type { options[name] }
+          next
+        end
+
+        types = params[name]
+        result[key] = types ? param.map_type { convert(types) } : param
+      end
+    end
+
+    def param_types_by_name(yard_method)
+      yard_method.tags(:param).each_with_object({}) do |tag, result|
+        next unless tag.name && tag.types
+
+        result[tag.name.to_s.sub(/\A[*&]+/, "")] = tag.types
+      end
+    end
+
+    # Builds an `RBS::Types::Record` (`{ key: Type, ?key2: Type2 }`) for each
+    # parameter documented with YARD `@option` tags, keyed by that
+    # parameter's name.
+    #
+    # e.g. `@option opts [String] :subject` contributes a `:subject` field
+    # to the record built for the `opts` parameter. Every field is
+    # optional, since that's what an options hash means: you're never
+    # required to pass any particular key.
+    def option_records_by_name(yard_method)
+      groups = yard_method.tags(:option).group_by { |tag| tag.name.to_s }
+
+      groups.filter_map do |name, tags|
+        fields = tags.each_with_object({}) do |tag, result|
+          pair = tag.pair
+          next unless pair&.name
+
+          key = pair.name.to_s.sub(/\A:/, "").to_sym
+          result[key] = [convert(pair.types), false]
+        end
+
+        [name, RBS::Types::Record.new(all_fields: fields, location: nil)] unless fields.empty?
+      end.to_h
+    end
+
+    def return_type_for(function, yard_method)
+      return function.return_type if yard_method.name == :initialize && yard_method.scope == :instance
+
+      types = return_types_of(yard_method)
+      types.empty? ? function.return_type : convert(types)
+    end
+
+    def return_types_of(yard_object)
+      return [] unless yard_object
+
+      yard_object.tags(:return).flat_map { |tag| tag.types || [] }
+    end
+
+    def convert(types)
+      TypeConverter.convert(types, strict: @strict)
+    end
+
+    def safe_symbol(name)
+      (name.nil? || name.empty?) ? nil : name.to_sym
+    end
+  end
+end

data/lib/yarbs/cli.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Yarbs
+  # The `yarbs` command line executable.
+  module CLI
+    # Parses ARGV and runs yarbs from the command line.
+    #
+    # @param argv [Array<String>]
+    # @return [void]
+    def self.run(argv)
+      output_dir = "sig"
+      watch = false
+      strict = false
+
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: yarbs [options] GLOB [GLOB ...]"
+        opts.on("-o", "--output DIR", "Directory to write .rbs files into (default: sig)") do |dir|
+          output_dir = dir
+        end
+        opts.on("-w", "--watch", "Watch the matched files and regenerate on change") do
+          watch = true
+        end
+        opts.on("-s", "--strict", "Raise instead of falling back to `untyped` on a YARD documentation error") do
+          strict = true
+        end
+      end
+
+      patterns = parser.parse(argv)
+
+      if patterns.empty?
+        warn parser.help
+        exit 1
+      end
+
+      if strict && watch
+        warn "yarbs: --strict cannot be combined with --watch"
+        exit 1
+      end
+
+      return Watcher.new(patterns, output_dir: output_dir).run if watch
+
+      begin
+        written = Yarbs.generate(patterns, output_dir: output_dir, strict: strict)
+      rescue Error => e
+        warn e.message
+        exit 1
+      end
+
+      if written.empty?
+        warn "yarbs: no files matched #{patterns.join(" ")}"
+        exit 1
+      end
+
+      written.each { |path| puts "wrote #{path}" }
+    end
+  end
+end

data/lib/yarbs/generator.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "rbs"
+require "yard"
+
+module Yarbs
+  # Orchestrates a full run: expands the glob patterns, loads YARD
+  # documentation for the matched files, and writes an annotated +.rbs+ file
+  # per source file into the output directory.
+  class Generator
+    # Runs a full generation pass for the given glob patterns.
+    #
+    # @param patterns [Array<String>] glob patterns for Ruby source files
+    # @param output_dir [String] directory to write generated .rbs files into
+    # @param strict [Boolean] raise instead of skipping a file or falling
+    #   back to +untyped+ when something can't be converted
+    # @return [Array<Pathname>] paths of the files written
+    def self.run(patterns, output_dir: "sig", strict: false)
+      new(output_dir, strict).run(patterns)
+    end
+
+    def initialize(output_dir, strict = false)
+      @output_dir = Pathname.new(output_dir)
+      @strict = strict
+    end
+
+    def run(patterns)
+      files = patterns.flat_map { |pattern| Dir.glob(pattern) }.uniq.select { |file| File.file?(file) }
+      return [] if files.empty?
+
+      # `YARD.parse` only populates the in-memory Registry: unlike
+      # `YARD::Registry.load`, it neither reads nor writes a `.yardoc` cache
+      # directory, so each run reflects exactly the files we were given.
+      YARD::Registry.clear
+      YARD.parse(files)
+
+      files.filter_map { |file| generate_file(file) }
+    end
+
+    private
+
+    # A single file with a (possibly transient, e.g. mid-edit) syntax error
+    # shouldn't stop the rest of the batch from generating: skip it and warn,
+    # unless running in strict mode, where it's treated as a hard failure.
+    def generate_file(file)
+      decls = PrototypeBuilder.build(File.read(file))
+      annotated = Annotator.annotate(decls, strict: @strict)
+
+      out_path = @output_dir.join(relative_sig_path(file))
+      out_path.dirname.mkpath
+      out_path.open("w") { |io| RBS::Writer.new(out: io).write(annotated) }
+
+      out_path
+    rescue SyntaxError => e
+      raise Error, "yarbs: syntax error in #{file} (#{e.message})" if @strict
+
+      warn "yarbs: skipping #{file} (#{e.message})"
+      nil
+    end
+
+    # Mirrors the source file's path under the output directory, stripping a
+    # leading `lib/` or `app/` (the conventional Ruby load-path roots) so
+    # `lib/foo/bar.rb` becomes `<output_dir>/foo/bar.rbs`.
+    def relative_sig_path(file)
+      parts = Pathname.new(file).cleanpath.each_filename.to_a
+      parts.shift if %w[lib app].include?(parts.first)
+      parts[-1] = parts[-1].sub(/\.rb\z/, ".rbs")
+      Pathname.new(File.join(*parts))
+    end
+  end
+end

data/lib/yarbs/prototype_builder.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rbs"
+
+module Yarbs
+  # Parses Ruby source into an +RBS::AST::Declarations+ tree with the
+  # correct structure (arity, visibility, singleton vs. instance, etc.) but
+  # every type left as +untyped+.
+  #
+  # This is exactly what `rbs prototype rb` does under the hood.
+  module PrototypeBuilder
+    # Parses Ruby source into its structural (untyped) RBS declarations.
+    #
+    # @param source [String] Ruby source code
+    # @return [Array<RBS::AST::Declarations::t>]
+    def self.build(source)
+      builder = RBS::Prototype::RB.new
+      builder.parse(source)
+      builder.decls
+    end
+  end
+end

data/lib/yarbs/type_converter.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "rbs"
+
+module Yarbs
+  # Converts YARD type strings (e.g. "Array<String>", "Boolean") into RBS
+  # types, falling back to +untyped+ for anything that doesn't map cleanly.
+  module TypeConverter
+    UNTYPED = RBS::Types::Bases::Any.new(location: nil)
+
+    # Converts a YARD tag's type list into a single RBS type.
+    #
+    # @param yard_types [Array<String>, nil] the raw strings from a YARD
+    #   tag's +types+ (e.g. +["String", "nil"]+ for +@param [String, nil]+)
+    # @param strict [Boolean] raise instead of falling back to +untyped+
+    #   when a type can't be converted
+    # @return [RBS::Types::t] the best matching RBS type, or +untyped+
+    def self.convert(yard_types, strict: false)
+      return UNTYPED if yard_types.nil? || yard_types.empty?
+
+      source = yard_types.map { |type| rewrite(type) }.join(" | ")
+
+      begin
+        RBS::Parser.parse_type(source, require_eof: true) || UNTYPED
+      rescue RBS::ParsingError => e
+        message = "yarbs: could not convert YARD type `#{yard_types.join(", ")}` to RBS (#{e.message})"
+        raise Error, message if strict
+
+        warn "#{message}; using untyped"
+        UNTYPED
+      end
+    end
+
+    # `Proc<(ArgType, ...), ReturnType>` -> `^(ArgType, ...) -> ReturnType`,
+    # RBS's proc-literal type (a real, typed callable signature).
+    #
+    # YARD's own tag parser mangles a literal `->` written inside
+    # `@param [...]` brackets, so this convention avoids the arrow entirely.
+    PROC_TYPE = /\AProc<\((?<args>.*)\),\s*(?<return_type>.+)>\z/m
+    private_constant :PROC_TYPE
+
+    # Rewrites a single YARD type string into RBS syntax, best-effort.
+    #
+    # @param type [String] a single YARD type string
+    # @return [String] the same type rewritten using RBS syntax, best-effort
+    def self.rewrite(type)
+      type = type.strip
+      return "untyped" if type.start_with?("#")
+
+      if (match = PROC_TYPE.match(type))
+        args = split_top_level(match[:args]).map { |arg| rewrite(arg) }
+        return "^(#{args.join(", ")}) -> #{rewrite(match[:return_type])}"
+      end
+
+      type = type.gsub(/\bBool(?:ean)?\b/, "bool")
+      type = type.gsub(/\bClass<(.+)>/) { "singleton(#{Regexp.last_match(1)})" }
+      type = type.gsub(/\bHash\{\s*(.+?)\s*=>\s*(.+?)\s*\}/m) { "Hash[#{Regexp.last_match(1)}, #{Regexp.last_match(2)}]" }
+      type.tr("<>", "[]")
+    end
+    private_class_method :rewrite
+
+    # Splits on top-level commas only, respecting `<>`/`{}`/`()`/`[]`
+    # nesting, so e.g. `Array<String>, Integer` splits into two, not three.
+    #
+    # @param str [String]
+    # @return [Array<String>]
+    def self.split_top_level(str)
+      return [] if str.strip.empty?
+
+      depth = 0
+      parts = []
+      current = +""
+
+      str.each_char do |char|
+        case char
+        when "<", "{", "(", "["
+          depth += 1
+          current << char
+        when ">", "}", ")", "]"
+          depth -= 1
+          current << char
+        when ","
+          if depth.zero?
+            parts << current.strip
+            current = +""
+          else
+            current << char
+          end
+        else
+          current << char
+        end
+      end
+
+      parts << current.strip
+    end
+    private_class_method :split_top_level
+  end
+end

data/lib/yarbs/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Yarbs
+  VERSION = "0.1.0"
+end

data/lib/yarbs/watcher.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "listen"
+require "pathname"
+
+module Yarbs
+  # Watches the files matched by a set of glob patterns (using the `listen`
+  # gem) and regenerates their RBS signatures whenever one of them changes.
+  #
+  # Used by `yarbs --watch` while developing an app with Yarbs support.
+  class Watcher
+    # Sets up a watcher for the given glob patterns.
+    #
+    # @param patterns [Array<String>] glob patterns for Ruby source files
+    # @param output_dir [String] directory to write generated .rbs files into
+    def initialize(patterns, output_dir:)
+      @patterns = patterns
+      @output_dir = output_dir
+    end
+
+    # Starts watching and blocks until interrupted (Ctrl-C).
+    #
+    # @return [void]
+    def run
+      generate("starting up")
+
+      directories = watch_directories
+      if directories.empty?
+        warn "yarbs: nothing to watch for #{@patterns.join(" ")}"
+        return
+      end
+
+      listener = Listen.to(*directories) { |modified, added, removed| on_change(modified + added + removed) }
+      listener.start
+
+      wait_for_interrupt
+    ensure
+      listener&.stop
+      puts "yarbs: stopped watching"
+    end
+
+    private
+
+    def wait_for_interrupt
+      stopped = false
+      trap("INT") { stopped = true }
+      sleep 0.2 until stopped
+    end
+
+    def on_change(paths)
+      changed = paths.select { |path| matches_patterns?(path) }
+      return if changed.empty?
+
+      generate("#{changed.size} file#{"s" unless changed.size == 1} changed")
+    end
+
+    def generate(reason)
+      puts "yarbs: #{reason}, regenerating..."
+      written = Yarbs.generate(@patterns, output_dir: @output_dir)
+      puts "yarbs: wrote #{written.size} file#{"s" unless written.size == 1} to #{@output_dir}"
+    rescue => e
+      warn "yarbs: #{e.class}: #{e.message}"
+    end
+
+    def matches_patterns?(path)
+      relative = relative_path(path)
+      @patterns.any? { |pattern| File.fnmatch?(pattern, relative, File::FNM_PATHNAME | File::FNM_EXTGLOB) }
+    end
+
+    def relative_path(path)
+      Pathname.new(path).relative_path_from(Pathname.pwd).to_s
+    rescue ArgumentError
+      path
+    end
+
+    def watch_directories
+      @patterns.filter_map { |pattern| base_directory(pattern) }.uniq.select { |dir| Dir.exist?(dir) }
+    end
+
+    # The directory to hand to `Listen.to` for a glob pattern: everything
+    # before its first glob character, e.g. "lib/**/*.rb" -> "lib".
+    def base_directory(pattern)
+      glob_index = pattern.index(/[*?{\[]/)
+      return File.dirname(pattern) unless glob_index
+
+      prefix = pattern[0...glob_index]
+      return "." if prefix.empty?
+
+      prefix.end_with?("/") ? prefix.chomp("/") : File.dirname(prefix)
+    end
+  end
+end

data/lib/yarbs.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "yard"
+require "rbs"
+
+require_relative "yarbs/version"
+require_relative "yarbs/type_converter"
+require_relative "yarbs/prototype_builder"
+require_relative "yarbs/annotator"
+require_relative "yarbs/generator"
+require_relative "yarbs/watcher"
+require_relative "yarbs/cli"
+
+module Yarbs
+  class Error < StandardError; end
+
+  # Generates .rbs signature files for the Ruby source files matched by
+  # +patterns+, writing them into +output_dir+.
+  #
+  # @param patterns [Array<String>] glob patterns for Ruby source files
+  # @param output_dir [String] directory to write generated .rbs files into
+  # @param strict [Boolean] raise a {Yarbs::Error} instead of skipping a file
+  #   or falling back to +untyped+ when something can't be converted
+  # @return [Array<Pathname>] paths of the files written
+  def self.generate(patterns, output_dir: "sig", strict: false)
+    Generator.run(Array(patterns), output_dir: output_dir, strict: strict)
+  end
+end

data/sig/yarbs/annotator.rbs

@@ -0,0 +1,75 @@
+module Yarbs
+  # Walks an +RBS::AST::Declarations+ tree produced by {PrototypeBuilder} and
+  # fills in its +untyped+ placeholders with types read from the matching
+  # YARD documentation (already loaded into +YARD::Registry+).
+  class Annotator
+    @strict: untyped
+
+    # Fills in the +untyped+ placeholders in a decls tree using YARD documentation.
+    #
+    # @param decls [Array<RBS::AST::Declarations::t>]
+    # @param strict [Boolean] raise instead of falling back to +untyped+
+    #   when a YARD type can't be converted
+    # @return [Array<RBS::AST::Declarations::t>] a new tree with YARD-derived types merged in
+    def self.annotate: (Array[RBS::AST::Declarations::t] decls, ?strict: bool) -> Array[RBS::AST::Declarations::t]
+
+    def initialize: (untyped strict) -> void
+
+    def visit_all: (untyped decls, untyped namespace) -> untyped
+
+    def visit: (untyped decl, untyped namespace) -> untyped
+
+    private
+
+    def annotate_constant: (untyped decl, untyped namespace) -> untyped
+
+    def annotate_method: (untyped member, untyped namespace) -> untyped
+
+    def annotate_attribute: (untyped member, untyped namespace) -> untyped
+
+    def annotate_overload: (untyped overload, untyped yard_method) -> untyped
+
+    def annotate_function: (untyped function, untyped yard_method) -> untyped
+
+    def annotate_block: (untyped block, untyped yard_method) -> untyped
+
+    def annotate_block_function: (untyped function, untyped yield_params, untyped new_return_type) -> untyped
+
+    # There's no arity to preserve here, but if `@yieldparam` tags exist we
+    # at least know the documented shape, so build a full positional-only
+    # `Function` from them instead of leaving the block's params untyped.
+    def annotate_untyped_block_function: (untyped function, untyped yield_params, untyped new_return_type) -> untyped
+
+    # Applies the type documented for a single structural parameter.
+    #
+    # @param unwrap [Symbol, nil] for a rest parameter (`*args`/`**kwargs`),
+    #   YARD conventionally documents the *collected* type (`Array<String>`,
+    #   `Hash{Symbol => String}`), but RBS's `*`/`**` types describe a single
+    #   element instead, so one layer of `Array`/`Hash` is stripped back off.
+    def annotate_param: (untyped param, untyped params, untyped options, ?unwrap: Symbol | nil) -> untyped
+
+    def unwrap_rest_type: (untyped type, untyped unwrap) -> untyped
+
+    def annotate_keywords: (untyped keywords, untyped params, untyped options) -> untyped
+
+    def param_types_by_name: (untyped yard_method) -> untyped
+
+    # Builds an `RBS::Types::Record` (`{ key: Type, ?key2: Type2 }`) for each
+    # parameter documented with YARD `@option` tags, keyed by that
+    # parameter's name.
+    #
+    # e.g. `@option opts [String] :subject` contributes a `:subject` field
+    # to the record built for the `opts` parameter. Every field is
+    # optional, since that's what an options hash means: you're never
+    # required to pass any particular key.
+    def option_records_by_name: (untyped yard_method) -> untyped
+
+    def return_type_for: (untyped function, untyped yard_method) -> untyped
+
+    def return_types_of: (untyped yard_object) -> (::Array[untyped] | untyped)
+
+    def convert: (untyped types) -> untyped
+
+    def safe_symbol: (untyped name) -> (nil | untyped)
+  end
+end

data/sig/yarbs/cli.rbs

@@ -0,0 +1,10 @@
+module Yarbs
+  # The `yarbs` command line executable.
+  module CLI
+    # Parses ARGV and runs yarbs from the command line.
+    #
+    # @param argv [Array<String>]
+    # @return [void]
+    def self.run: (Array[String] argv) -> void
+  end
+end

data/sig/yarbs/generator.rbs

@@ -0,0 +1,35 @@
+module Yarbs
+  # Orchestrates a full run: expands the glob patterns, loads YARD
+  # documentation for the matched files, and writes an annotated +.rbs+ file
+  # per source file into the output directory.
+  class Generator
+    @output_dir: untyped
+
+    @strict: untyped
+
+    # Runs a full generation pass for the given glob patterns.
+    #
+    # @param patterns [Array<String>] glob patterns for Ruby source files
+    # @param output_dir [String] directory to write generated .rbs files into
+    # @param strict [Boolean] raise instead of skipping a file or falling
+    #   back to +untyped+ when something can't be converted
+    # @return [Array<Pathname>] paths of the files written
+    def self.run: (untyped patterns, ?output_dir: ::String, ?strict: bool) -> untyped
+
+    def initialize: (untyped output_dir, ?bool strict) -> void
+
+    def run: (untyped patterns) -> (::Array[untyped] | untyped)
+
+    private
+
+    # A single file with a (possibly transient, e.g. mid-edit) syntax error
+    # shouldn't stop the rest of the batch from generating: skip it and warn,
+    # unless running in strict mode, where it's treated as a hard failure.
+    def generate_file: (untyped file) -> untyped
+
+    # Mirrors the source file's path under the output directory, stripping a
+    # leading `lib/` or `app/` (the conventional Ruby load-path roots) so
+    # `lib/foo/bar.rb` becomes `<output_dir>/foo/bar.rbs`.
+    def relative_sig_path: (untyped file) -> untyped
+  end
+end

data/sig/yarbs/prototype_builder.rbs

@@ -0,0 +1,14 @@
+module Yarbs
+  # Parses Ruby source into an +RBS::AST::Declarations+ tree with the
+  # correct structure (arity, visibility, singleton vs. instance, etc.) but
+  # every type left as +untyped+.
+  #
+  # This is exactly what `rbs prototype rb` does under the hood.
+  module PrototypeBuilder
+    # Parses Ruby source into its structural (untyped) RBS declarations.
+    #
+    # @param source [String] Ruby source code
+    # @return [Array<RBS::AST::Declarations::t>]
+    def self.build: (String source) -> Array[RBS::AST::Declarations::t]
+  end
+end

data/sig/yarbs/type_converter.rbs

@@ -0,0 +1,36 @@
+module Yarbs
+  # Converts YARD type strings (e.g. "Array<String>", "Boolean") into RBS
+  # types, falling back to +untyped+ for anything that doesn't map cleanly.
+  module TypeConverter
+    UNTYPED: untyped
+
+    # Converts a YARD tag's type list into a single RBS type.
+    #
+    # @param yard_types [Array<String>, nil] the raw strings from a YARD
+    #   tag's +types+ (e.g. +["String", "nil"]+ for +@param [String, nil]+)
+    # @param strict [Boolean] raise instead of falling back to +untyped+
+    #   when a type can't be converted
+    # @return [RBS::Types::t] the best matching RBS type, or +untyped+
+    def self.convert: (Array[String] | nil yard_types, ?strict: bool) -> RBS::Types::t
+
+    # `Proc<(ArgType, ...), ReturnType>` -> `^(ArgType, ...) -> ReturnType`,
+    # RBS's proc-literal type (a real, typed callable signature).
+    #
+    # YARD's own tag parser mangles a literal `->` written inside
+    # `@param [...]` brackets, so this convention avoids the arrow entirely.
+    PROC_TYPE: ::Regexp
+
+    # Rewrites a single YARD type string into RBS syntax, best-effort.
+    #
+    # @param type [String] a single YARD type string
+    # @return [String] the same type rewritten using RBS syntax, best-effort
+    def self.rewrite: (String type) -> String
+
+    # Splits on top-level commas only, respecting `<>`/`{}`/`()`/`[]`
+    # nesting, so e.g. `Array<String>, Integer` splits into two, not three.
+    #
+    # @param str [String]
+    # @return [Array<String>]
+    def self.split_top_level: (String str) -> Array[String]
+  end
+end

data/sig/yarbs/version.rbs

@@ -0,0 +1,3 @@
+module Yarbs
+  VERSION: "0.1.0"
+end

data/sig/yarbs/watcher.rbs

@@ -0,0 +1,40 @@
+module Yarbs
+  # Watches the files matched by a set of glob patterns (using the `listen`
+  # gem) and regenerates their RBS signatures whenever one of them changes.
+  #
+  # Used by `yarbs --watch` while developing an app with Yarbs support.
+  class Watcher
+    @patterns: untyped
+
+    @output_dir: untyped
+
+    # Sets up a watcher for the given glob patterns.
+    #
+    # @param patterns [Array<String>] glob patterns for Ruby source files
+    # @param output_dir [String] directory to write generated .rbs files into
+    def initialize: (Array[String] patterns, output_dir: String) -> void
+
+    # Starts watching and blocks until interrupted (Ctrl-C).
+    #
+    # @return [void]
+    def run: () -> void
+
+    private
+
+    def wait_for_interrupt: () -> untyped
+
+    def on_change: (untyped paths) -> (nil | untyped)
+
+    def generate: (untyped reason) -> untyped
+
+    def matches_patterns?: (untyped path) -> bool
+
+    def relative_path: (untyped path) -> untyped
+
+    def watch_directories: () -> untyped
+
+    # The directory to hand to `Listen.to` for a glob pattern: everything
+    # before its first glob character, e.g. "lib/**/*.rb" -> "lib".
+    def base_directory: (untyped pattern) -> (untyped | ".")
+  end
+end

data/sig/yarbs.rbs

@@ -0,0 +1,14 @@
+module Yarbs
+  class Error < StandardError
+  end
+
+  # Generates .rbs signature files for the Ruby source files matched by
+  # +patterns+, writing them into +output_dir+.
+  #
+  # @param patterns [Array<String>] glob patterns for Ruby source files
+  # @param output_dir [String] directory to write generated .rbs files into
+  # @param strict [Boolean] raise a {Yarbs::Error} instead of skipping a file
+  #   or falling back to +untyped+ when something can't be converted
+  # @return [Array<Pathname>] paths of the files written
+  def self.generate: (Array[String] patterns, ?output_dir: String, ?strict: bool) -> Array[Pathname]
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: yarbs
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- tobidelius
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: listen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: rbs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+email:
+- tobidelius@gmail.com
+executables:
+- yarbs
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/yarbs
+- lib/yarbs.rb
+- lib/yarbs/annotator.rb
+- lib/yarbs/cli.rb
+- lib/yarbs/generator.rb
+- lib/yarbs/prototype_builder.rb
+- lib/yarbs/type_converter.rb
+- lib/yarbs/version.rb
+- lib/yarbs/watcher.rb
+- sig/yarbs.rbs
+- sig/yarbs/annotator.rbs
+- sig/yarbs/cli.rbs
+- sig/yarbs/generator.rbs
+- sig/yarbs/prototype_builder.rbs
+- sig/yarbs/type_converter.rbs
+- sig/yarbs/version.rbs
+- sig/yarbs/watcher.rbs
+homepage: https://github.com/tobidelius/yarbs
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Generate RBS files from YARD documentation.
+test_files: []