yarbs 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14192c2d967c20c40a4ed4e9d24d810b6bcaf8fa957261c27d904301f5d6e980
-  data.tar.gz: 7a2bc9f86103deaf360be3c6fabcd5895d6bca0280ab1f0c95a426921852448f
+  metadata.gz: ad6ad92289f8a7d901231eadb81be04511912ffd65f183d0cd00d4f9d2b9b851
+  data.tar.gz: 1cae1aaf74795fef87a77eafd33b32c7a8252dd3c0660032d11c9985213ab965
 SHA512:
-  metadata.gz: 50961f4fa46908f161a8748602fa2a282cbb00a018a44d7f701b96043e7ceb1332359526318359efd7d86cdce8fa944aac2a442d7daedd70a7caa5eb0e24b74e
-  data.tar.gz: 5f59a649d92e618223e4b60bd23d05b7e2a7f68a08818a70083bf17b5981e2e11cf2bc2a55f9821528fc1359c36da04d976cb4b1db021209b79d98dc119e16d3
+  metadata.gz: dce1a1abee4e2d215abf7fc9ca707c00dc166790d86daa644d2bd43ab29348dade7eda387ada1ac39d0bad428e19f4d19321cf57af465d5490376d06fb02b78d
+  data.tar.gz: 84096e966259189840b11c1e7d02d5e2b1cbd29fe429d262e9e8733d0d503505ae92706ac3effcbdaafe6fb903fe152bb69cad59159d979862f7cbd37726451e

data/README.md

@@ -102,6 +102,8 @@ see:
   (`@yieldparam`/`@yieldreturn`), and typing a `Proc`/lambda parameter
 - [docs/classes.md](docs/classes.md) — classes, modules, nesting,
   inheritance, mixins, `attr_*`, constants, and visibility
+- [docs/deprecated.md](docs/deprecated.md) — `@deprecated`, turned into
+  `%a{deprecated}` so Steep warns wherever deprecated code is used
 
 ## Development
 
@@ -114,12 +116,6 @@ for yarbs' own dependencies. From there:
 - `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

data/lib/yarbs/annotator.rb

@@ -30,7 +30,10 @@ module Yarbs
       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))
+        decl.update(
+          members: visit_all(decl.members, inner_namespace),
+          annotations: with_deprecation(decl.annotations, YARD::Registry.at(inner_namespace.join("::")))
+        )
       when RBS::AST::Declarations::Constant
         annotate_constant(decl, namespace)
       when RBS::AST::Members::MethodDefinition
@@ -47,14 +50,13 @@ module Yarbs
     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),
+        type: types.empty? ? decl.type : convert(types),
         location: decl.location,
         comment: decl.comment,
-        annotations: decl.annotations
+        annotations: with_deprecation(decl.annotations, yard_object)
       )
     end
 
@@ -64,7 +66,7 @@ module Yarbs
       return member unless yard_method
 
       overloads = member.overloads.map { |overload| annotate_overload(overload, yard_method) }
-      member.update(overloads: overloads)
+      member.update(overloads: overloads, annotations: with_deprecation(member.annotations, yard_method))
     end
 
     def annotate_attribute(member, namespace)
@@ -75,9 +77,11 @@ module Yarbs
       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))
+      member.update(
+        type: types.empty? ? member.type : convert(types),
+        annotations: with_deprecation(member.annotations, yard_attr)
+      )
     end
 
     def annotate_overload(overload, yard_method)
@@ -130,7 +134,29 @@ module Yarbs
         function
       end
 
-      RBS::Types::Block.new(type: new_function, required: block.required, self_type: block.self_type)
+      required = block.required && !optional_block?(block, yard_method)
+      RBS::Types::Block.new(type: new_function, required: required, self_type: block.self_type)
+    end
+
+    # `rbs prototype rb` marks an explicit `&block` as required unless the
+    # body checks `block_given?` or only uses the block conditionally, so a
+    # block that's merely captured or forwarded (`other(&block)`) comes out
+    # required. Treat the block as optional when:
+    #
+    # - its `@param` tag includes `nil` (`@param block [Proc, nil]`), or
+    # - the body never `yield`s (the block type is an `UntypedFunction`) and
+    #   no `@yield`/`@yieldparam`/`@yieldreturn` tag documents a contract
+    #   for callers to fulfil.
+    def optional_block?(block, yard_method)
+      block_param = yard_method.parameters.find { |name, _| name.to_s.start_with?("&") }&.first
+      return false unless block_param
+
+      name = block_param.to_s.delete_prefix("&")
+      tag = yard_method.tags(:param).find { |param| param.name.to_s.delete_prefix("&") == name }
+      return true if tag&.types&.include?("nil")
+
+      block.type.is_a?(RBS::Types::UntypedFunction) &&
+        %i[yield yieldparam yieldreturn].none? { |tag_name| yard_method.has_tag?(tag_name) }
     end
 
     def annotate_block_function(function, yield_params, new_return_type)
@@ -263,6 +289,24 @@ module Yarbs
       yard_object.tags(:return).flat_map { |tag| tag.types || [] }
     end
 
+    # Appends a `%a{deprecated}` annotation when the YARD object has a
+    # `@deprecated` tag, which Steep reports as `Ruby::DeprecatedReference`
+    # wherever the declaration is used. The tag's text becomes the message
+    # (`%a{deprecated: Use #bar instead}`), flattened onto one line since
+    # Steep only reads the message up to the first newline.
+    def with_deprecation(annotations, yard_object)
+      tag = yard_object&.tag(:deprecated)
+      return annotations unless tag
+
+      message = tag.text.to_s.split.join(" ")
+      string = message.empty? ? "deprecated" : "deprecated: #{message}"
+      # RBS::Writer picks whichever %a delimiter pair doesn't appear in the
+      # string, and raises if every one of them does.
+      string = "deprecated" if ["}", ")", "]", ">", "|"].all? { |char| string.include?(char) }
+
+      annotations + [RBS::AST::Annotation.new(string: string, location: nil)]
+    end
+
     def convert(types)
       TypeConverter.convert(types, strict: @strict)
     end

data/lib/yarbs/generator.rb

@@ -49,7 +49,7 @@ module Yarbs
 
       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.open("w") { |io| Writer.new(out: io).write(annotated) }
 
       out_path
     rescue SyntaxError => e

data/lib/yarbs/type_converter.rb

@@ -21,7 +21,8 @@ module Yarbs
       source = yard_types.map { |type| rewrite(type) }.join(" | ")
 
       begin
-        RBS::Parser.parse_type(source, require_eof: true) || UNTYPED
+        type = RBS::Parser.parse_type(source, require_eof: true)
+        type ? fit_generic_args(type) : UNTYPED
       rescue RBS::ParsingError => e
         message = "yarbs: could not convert YARD type `#{yard_types.join(", ")}` to RBS (#{e.message})"
         raise Error, message if strict
@@ -31,6 +32,50 @@ module Yarbs
       end
     end
 
+    # Number of type parameters for the core generic classes, which YARD
+    # lets you write with any number of arguments (or none) but RBS doesn't.
+    GENERIC_ARITY = {
+      Array: 1,
+      Set: 1,
+      Range: 1,
+      Enumerable: 1,
+      Enumerator: 2,
+      Hash: 2
+    }.freeze
+    private_constant :GENERIC_ARITY
+
+    # Fits the arguments of core generics to what RBS expects, recursively:
+    #
+    # - bare `Array`/`Hash` -> `Array[untyped]`/`Hash[untyped, untyped]`
+    # - `Array<String, Regexp>` (YARD for "Strings or Regexps") ->
+    #   `Array[String | Regexp]`
+    # - missing trailing arguments are filled with `untyped`
+    #
+    # @param type [RBS::Types::t]
+    # @return [RBS::Types::t]
+    def self.fit_generic_args(type)
+      case type
+      when RBS::Types::ClassInstance
+        args = type.args.map { |arg| fit_generic_args(arg) }
+        arity = type.name.namespace.path.empty? ? GENERIC_ARITY[type.name.name] : nil
+
+        if arity
+          if arity == 1 && args.size > 1
+            args = [RBS::Types::Union.new(types: args, location: nil)]
+          elsif args.size < arity
+            args += Array.new(arity - args.size, UNTYPED)
+          end
+        end
+
+        RBS::Types::ClassInstance.new(name: type.name, args: args, location: type.location)
+      when RBS::Types::Union, RBS::Types::Intersection, RBS::Types::Optional, RBS::Types::Tuple, RBS::Types::Record, RBS::Types::Proc
+        type.map_type { |inner| fit_generic_args(inner) }
+      else
+        type
+      end
+    end
+    private_class_method :fit_generic_args
+
     # `Proc<(ArgType, ...), ReturnType>` -> `^(ArgType, ...) -> ReturnType`,
     # RBS's proc-literal type (a real, typed callable signature).
     #

data/lib/yarbs/version.rb

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

data/lib/yarbs/writer.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "rbs"
+
+module Yarbs
+  # An +RBS::Writer+ that also writes a constant's annotations, which the
+  # stock writer drops (even though the RBS parser accepts +%a{...}+ on a
+  # constant, and Steep reads it). Without this, a +@deprecated+ constant
+  # would silently lose the +%a{deprecated}+ that {Annotator} gives it.
+  class Writer < RBS::Writer
+    private
+
+    def write_decl(decl)
+      return super unless decl.is_a?(RBS::AST::Declarations::Constant)
+
+      write_comment decl.comment
+      write_annotation decl.annotations
+      puts "#{decl.name}: #{decl.type}"
+    end
+  end
+end

data/lib/yarbs.rb

@@ -7,6 +7,7 @@ require_relative "yarbs/version"
 require_relative "yarbs/type_converter"
 require_relative "yarbs/prototype_builder"
 require_relative "yarbs/annotator"
+require_relative "yarbs/writer"
 require_relative "yarbs/generator"
 require_relative "yarbs/watcher"
 require_relative "yarbs/cli"

data/sig/yarbs/annotator.rbs

@@ -68,6 +68,13 @@ module Yarbs
 
     def return_types_of: (untyped yard_object) -> (::Array[untyped] | untyped)
 
+    # Appends a `%a{deprecated}` annotation when the YARD object has a
+    # `@deprecated` tag, which Steep reports as `Ruby::DeprecatedReference`
+    # wherever the declaration is used. The tag's text becomes the message
+    # (`%a{deprecated: Use #bar instead}`), flattened onto one line since
+    # Steep only reads the message up to the first newline.
+    def with_deprecation: (untyped annotations, untyped yard_object) -> untyped
+
     def convert: (untyped types) -> untyped
 
     def safe_symbol: (untyped name) -> (nil | untyped)

data/sig/yarbs/writer.rbs

@@ -0,0 +1,11 @@
+module Yarbs
+  # An +RBS::Writer+ that also writes a constant's annotations, which the
+  # stock writer drops (even though the RBS parser accepts +%a{...}+ on a
+  # constant, and Steep reads it). Without this, a +@deprecated+ constant
+  # would silently lose the +%a{deprecated}+ that {Annotator} gives it.
+  class Writer < RBS::Writer
+    private
+
+    def write_decl: (untyped decl) -> untyped
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yarbs
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - tobidelius
@@ -70,6 +70,7 @@ files:
 - lib/yarbs/type_converter.rb
 - lib/yarbs/version.rb
 - lib/yarbs/watcher.rb
+- lib/yarbs/writer.rb
 - sig/yarbs.rbs
 - sig/yarbs/annotator.rbs
 - sig/yarbs/cli.rbs
@@ -78,6 +79,7 @@ files:
 - sig/yarbs/type_converter.rbs
 - sig/yarbs/version.rbs
 - sig/yarbs/watcher.rbs
+- sig/yarbs/writer.rbs
 homepage: https://github.com/tobidelius/yarbs
 licenses:
 - MIT
@@ -96,7 +98,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Generate RBS files from YARD documentation.
 test_files: []