protostar 0.1.0.beta1

data/lib/protostar/compiler/emitters/protostar_rbs.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module Protostar
+  class Compiler
+    module Emitters
+      # Writes `_pb.rbs` signatures for the classes {Ruby} generates:
+      # subclasses of `Protostar::Message`, repeated fields as Arrays, maps as
+      # Hashes, writers typed as {Message::Coercion} accepts. Signatures for
+      # `Protostar::Message` itself are in the gem's `sig/protostar.rbs`.
+      # {Rbs} writes protoc's signatures for google-protobuf's classes instead.
+      class ProtostarRbs
+        INTEGERS = %i[fixed32 fixed64 int32 int64 sfixed32 sfixed64 sint32 sint64 uint32 uint64].freeze
+        # The mixins {WellKnown::MIXINS} includes, by full name, as RBS names
+        MIXINS = {
+          "google.protobuf.Any" => "::Protostar::WellKnown::Any",
+          "google.protobuf.Timestamp" => "::Protostar::WellKnown::Timestamp",
+          "google.protobuf.Duration" => "::Protostar::WellKnown::Duration",
+          "google.protobuf.Struct" => "::Protostar::WellKnown::Struct",
+          "google.protobuf.Value" => "::Protostar::WellKnown::Value",
+          "google.protobuf.ListValue" => "::Protostar::WellKnown::ListValue"
+        }.freeze
+        # Ruby values {Message::Coercion} turns into these messages
+        COERCED = {
+          "google.protobuf.Timestamp" => "::Time",
+          "google.protobuf.Duration" => "::Numeric"
+        }.freeze
+
+        # @param namespaces [Hash{String => String}] Ruby module paths by file name, as {Ruby} takes them
+        def initialize(namespaces: {})
+          @namespaces = namespaces
+          @reserved = Message::Accessors.reserved
+        end
+
+        # @param files [Array<Schema::File>]
+        # @return [Hash{String => String}] output path to signatures
+        def emit(files)
+          files.to_h { |f| [Naming.require_name(f.name) + ".rbs", file(f)] }
+        end
+
+        # @param file [Schema::File]
+        # @return [String]
+        def file(file)
+          Naming.check_ruby_package(file)
+          @source = file.source_info
+          p = Printer.new
+          p.print("# Generated by protostar from #{file.name}. Do not edit.\n")
+          modules = module_path(file)
+          unless file.messages.empty? && file.enums.empty?
+            p.print("\n")
+            modules.each do |m|
+              p.print("module #{m}\n")
+              p.indent
+            end
+            first = [true]
+            file.messages.each_with_index { |m, i| message(p, m, [4, i], first) }
+            file.enums.each_with_index { |e, i| enum(p, e, [5, i], first) }
+            modules.size.times do
+              p.outdent
+              p.print("end\n")
+            end
+          end
+          p.to_s
+        ensure
+          @source = nil
+        end
+
+        private
+
+        def module_path(file)
+          namespace = @namespaces[file.name]
+          namespace ||= "Protostar::#{Naming.module_path(file).join("::")}" if BOOTSTRAP.include?(file.name)
+          Naming.module_path(file, namespace)
+        end
+
+        def constant(descriptor)
+          prefix = module_path(descriptor.file).map { |m| "::#{m}" }.join
+          "#{prefix}::#{Naming.relative_constant(descriptor)}"
+        end
+
+        def blank(p, first)
+          if first[0]
+            first[0] = false
+          else
+            p.print("\n")
+          end
+        end
+
+        def comment(p, path)
+          text = @source&.location(path)&.leading_comments
+          return if text.nil? || text.empty?
+          text.split("\n").reject(&:empty?).each { |line| p.print("##{line}\n") }
+        end
+
+        def message?(field)
+          field.type == :message || field.type == :group
+        end
+
+        # What the reader returns for one value
+        def read_one(field)
+          case field.type
+          when :double, :float then "::Float"
+          when *INTEGERS then "::Integer"
+          when :bool then "bool"
+          when :string, :bytes then "::String"
+          when :enum then "#{constant(field.enum_type)}::names | ::Integer"
+          else constant(field.message_type)
+          end
+        end
+
+        # What the writer takes for one value
+        def write_one(field)
+          case field.type
+          when :double, :float then "::Float | ::Integer"
+          when *INTEGERS then "::Integer"
+          when :bool then "bool"
+          when :string, :bytes then "::String"
+          when :enum then "#{constant(field.enum_type)}::names | ::Integer"
+          else
+            name = constant(field.message_type)
+            [name, "#{name}::init_map", COERCED[field.message_type.full_name]].compact.join(" | ")
+          end
+        end
+
+        def read_type(field)
+          if field.map?
+            "::Hash[#{read_one(field.map_key)}, #{read_one(field.map_value)}]"
+          elsif field.repeated?
+            "::Array[#{read_one(field)}]"
+          elsif message?(field)
+            "#{constant(field.message_type)}?"
+          else
+            read_one(field)
+          end
+        end
+
+        def write_type(field)
+          inner = if field.map?
+            "::Hash[#{write_one(field.map_key)}, #{write_one(field.map_value)}]"
+          elsif field.repeated?
+            "::Array[#{write_one(field)}]"
+          else
+            write_one(field)
+          end
+          inner.include?("|") ? "(#{inner})?" : "#{inner}?"
+        end
+
+        def enum(p, enum, path, first)
+          blank(p, first)
+          comment(p, path)
+          p.print("module #{Naming.rubify_constant(enum.name)}\n")
+          p.indent
+          p.print("extend ::Protostar::Enum\n\n")
+          seen = {}
+          enum.values.each do |v|
+            const = Protostar::Enum.constant_name(v.name)
+            next if const.nil? || seen[const]
+            seen[const] = true
+            p.print("#{const}: #{v.number}\n")
+          end
+          p.print("\ntype names = #{enum.values.map { |v| ":#{symbol(v.name)}" }.uniq.join(" | ")}\n")
+          p.outdent
+          p.print("end\n")
+        end
+
+        # A Symbol literal for a name, quoted when RBS needs it
+        def symbol(name)
+          /\A[A-Za-z_][A-Za-z0-9_]*\z/.match?(name) ? name : name.inspect
+        end
+
+        def message(p, message, path, first)
+          return if message.map_entry?
+          blank(p, first)
+          comment(p, path)
+          p.print("class #{Naming.rubify_constant(message.name)} < ::Protostar::Message\n")
+          p.indent
+          inner = [true]
+          message.nested_messages.each_with_index { |m, i| message(p, m, path + [3, i], inner) }
+          message.nested_enums.each_with_index { |e, i| enum(p, e, path + [4, i], inner) }
+          blank(p, inner)
+          if (mixin = MIXINS[message.full_name])
+            p.print("include #{mixin}\nextend #{mixin}::ClassMethods\n\n")
+          end
+          init_map(p, message)
+          constructor(p, message)
+          taken = @reserved.dup
+          message.fields.each_with_index do |f, i|
+            accessors(p, f, path + [2, i], taken)
+          end
+          message.real_oneofs.each do |o|
+            which = :"which_#{o.name}"
+            next if taken[which]
+            taken[which] = true
+            names = o.fields.map { |f| ":#{f.name}" }.uniq.join(" | ")
+            p.print("def which_#{o.name}: () -> (#{names})?\n")
+          end
+          p.outdent
+          p.print("end\n")
+        end
+
+        def init_map(p, message)
+          if message.fields.empty?
+            p.print("type init_map = ::Hash[::Symbol | ::String, untyped]\n")
+            return
+          end
+          p.print("type init_map = {\n")
+          p.indent
+          message.fields.each_with_index do |f, i|
+            comma = (i == message.fields.size - 1) ? "" : ","
+            p.print("?#{f.name}: #{write_type(f)}#{comma}\n")
+          end
+          p.outdent
+          p.print("}\n")
+        end
+
+        # `new` takes a Hash, keywords, or both
+        def constructor(p, message)
+          if message.fields.empty?
+            p.print("def initialize: (?init_map? fields, **untyped) -> void\n")
+            return
+          end
+          p.print("def initialize: (\n")
+          p.indent
+          p.print("?init_map? fields")
+          message.fields.each { |f| p.print(",\n?#{f.name}: #{write_type(f)}") }
+          p.outdent
+          p.print("\n) -> void\n")
+        end
+
+        def accessors(p, field, path, taken)
+          name = field.name
+          read = read_type(field)
+          write = write_type(field)
+          reader = !taken[name.to_sym]
+          writer = !taken[:"#{name}="]
+          taken[name.to_sym] = taken[:"#{name}="] = true
+          if reader || writer
+            p.print("\n")
+            comment(p, path)
+            p.print("attr_reader #{name}(): #{read}\n") if reader
+            p.print("attr_writer #{name}(): #{write}\n") if writer
+          end
+          return unless field.presence?
+          has = :"has_#{name}?"
+          clear = :"clear_#{name}"
+          p.print("def #{has}: () -> bool\n") unless taken[has]
+          p.print("def #{clear}: () -> void\n") unless taken[clear]
+          taken[has] = taken[clear] = true
+        end
+      end
+    end
+  end
+end

data/lib/protostar/compiler/emitters/rbs.rb

@@ -0,0 +1,394 @@
+# frozen_string_literal: true
+
+module Protostar
+  class Compiler
+    module Emitters
+      # Writes the `_pb.rbs` signatures protoc's rbs_generator.cc writes.
+      # Leading comments come from source info, so compile with it.
+      class Rbs
+        WRAPPERS = %w[
+          google.protobuf.DoubleValue google.protobuf.FloatValue google.protobuf.Int64Value
+          google.protobuf.UInt64Value google.protobuf.Int32Value google.protobuf.UInt32Value
+          google.protobuf.StringValue google.protobuf.BytesValue google.protobuf.BoolValue
+        ].freeze
+        INTEGERS = %i[fixed32 fixed64 int32 int64 sfixed32 sfixed64 sint32 sint64 uint32 uint64].freeze
+        HEADER = "# Generated by the protocol buffer compiler.  DO NOT EDIT!\n" \
+          "# This RBS interface is provided for convenience, on a best-effort basis.\n" \
+          "# The library is the definitive source for the API contract; if the RBS file\n" \
+          "# and the library's behavior differ, the library behavior is authoritative.\n" \
+          "# We welcome fixes to change the RBS file to match.\n"
+
+        # @param files [Array<Schema::File>]
+        # @return [Hash{String => String}] output path to signatures
+        def emit(files)
+          files.to_h { |f| [Naming.require_name(f.name) + ".rbs", file(f)] }
+        end
+
+        # @param file [Schema::File]
+        # @return [String]
+        def file(file)
+          Naming.check_ruby_package(file)
+          @source = file.source_info
+          p = Printer.new
+          p.print("#{HEADER}# source: #{file.name}\n\n")
+          initial = [true]
+          modules = Naming.module_path(file)
+          modules.each do |m|
+            p.print("module #{m}\n")
+            p.indent
+          end
+          file.messages.each_with_index do |m, i|
+            mid_line(initial, p)
+            message(p, m, [4, i])
+          end
+          file.enums.each_with_index do |e, i|
+            mid_line(initial, p)
+            enum(p, e, [5, i])
+          end
+          modules.size.times do
+            p.outdent
+            p.print("end\n")
+          end
+          p.print("\n")
+          lookup_override(p, file)
+          p.to_s
+        ensure
+          @source = nil
+        end
+
+        private
+
+        def mid_line(initial, p)
+          if initial[0]
+            initial[0] = false
+          else
+            p.print("\n")
+          end
+        end
+
+        def separator(initial)
+          if initial[0]
+            initial[0] = false
+            "  "
+          else
+            "| "
+          end
+        end
+
+        def wrap_union(type)
+          type.include?("|") ? "(#{type})" : type
+        end
+
+        def optional(type)
+          type.end_with?("?") ? type : "#{wrap_union(type)}?"
+        end
+
+        def comment(p, path)
+          text = @source&.location(path)&.leading_comments
+          return if text.nil? || text.empty?
+          text.split("\n").reject(&:empty?).each { |line| p.print("##{line}\n") }
+        end
+
+        def deprecation(p, descriptor)
+          p.print("# @deprecated\n") if descriptor.options.deprecated?
+        end
+
+        # rbs_generator.cc's ModulePath: the package's modules as "::A::B"
+        def module_path(file)
+          convert = true
+          if (package = file.options.ruby_package)
+            convert = false if package.include?("::")
+          else
+            package = file.package
+          end
+          package = package.split(".", -1).map { |part| Naming.package_to_module(part) }.join("::") if convert
+          package.empty? ? "" : "::#{package}"
+        end
+
+        def message_name(message)
+          parent = message.containing_message
+          prefix = parent ? message_name(parent) : module_path(message.file)
+          "#{prefix}::#{Naming.rubify_constant(message.name)}"
+        end
+
+        def enum_name(enum)
+          parent = enum.containing_message
+          prefix = parent ? message_name(parent) : module_path(enum.file)
+          "#{prefix}::#{Naming.rubify_constant(enum.name)}"
+        end
+
+        def scalar_read(field)
+          case field.type
+          when :double, :float then "::Float"
+          when *INTEGERS then "::Integer"
+          when :bool then "bool"
+          when :string, :bytes then "::String"
+          when :enum then "#{enum_name(field.enum_type)}::names | ::Integer"
+          when :message, :group then message_name(field.message_type)
+          else "untyped"
+          end
+        end
+
+        def scalar_write(field)
+          case field.type
+          when :double, :float then "::Float | ::Integer"
+          when *INTEGERS then "::Integer | ::Float"
+          when :bool then "bool"
+          when :string then "::String | ::Symbol"
+          when :bytes then "::String"
+          when :enum
+            name = enum_name(field.enum_type)
+            "#{name}::names | #{name}::strings | ::Integer | ::Float"
+          when :message, :group
+            name = message_name(field.message_type)
+            case field.message_type.full_name
+            when "google.protobuf.Timestamp" then "#{name} | ::Time"
+            when "google.protobuf.Duration" then "#{name} | ::int"
+            else name
+            end
+          else "untyped"
+          end
+        end
+
+        def message?(field)
+          field.type == :message || field.type == :group
+        end
+
+        def read_type(field)
+          if field.map?
+            key = field.map_key
+            value = field.map_value
+            "::Google::Protobuf::Map[#{scalar_read(key)}, #{scalar_read(value)}, #{scalar_write(key)}, " \
+              "#{scalar_write(value)}]"
+          elsif field.repeated?
+            "::Google::Protobuf::RepeatedField[#{scalar_read(field)}, #{scalar_write(field)}]"
+          elsif message?(field)
+            optional(scalar_read(field))
+          else
+            scalar_read(field)
+          end
+        end
+
+        def write_type(field)
+          if field.map? || field.repeated?
+            read_type(field)
+          elsif message?(field) || field.real_oneof
+            optional(scalar_write(field))
+          else
+            scalar_write(field)
+          end
+        end
+
+        def init_type(field)
+          if field.map?
+            "::Hash[#{scalar_write(field.map_key)}, #{scalar_write(field.map_value)}]?"
+          elsif field.repeated?
+            "::Array[#{scalar_write(field)}]?"
+          elsif message?(field)
+            name = message_name(field.message_type)
+            optional("#{name} | #{name}::init_map")
+          else
+            optional(scalar_write(field))
+          end
+        end
+
+        def enum_value(p, value, path)
+          comment(p, path)
+          deprecation(p, value)
+          name = value.name
+          unless name[0].between?("A", "Z")
+            if name[0].between?("a", "z")
+              name = name[0].upcase + name[1..]
+            else
+              p.print("# Enum value '#{value.name}' does not start with an uppercase letter as is required for " \
+                "Ruby constants.\n# #{value.name}: #{value.number}\n")
+              return
+            end
+          end
+          p.print("#{name}: #{value.number}\n")
+        end
+
+        def enum(p, enum, path)
+          comment(p, path)
+          deprecation(p, enum)
+          initial = [true]
+          p.print("module #{Naming.rubify_constant(enum.name)}\n")
+          p.indent
+          mid_line(initial, p)
+          p.print("extend ::Google::Protobuf::_EnumModule\n")
+          enum.values.each_with_index do |v, i|
+            mid_line(initial, p)
+            enum_value(p, v, path + [2, i])
+          end
+          by_number = {}
+          enum.values.each { |v| (by_number[v.number] ||= []) << v.name }
+          mid_line(initial, p)
+          p.print("def self.lookup:\n")
+          p.indent
+          overload = [true]
+          by_number.each do |number, names|
+            p.print("#{separator(overload)}(#{number} number) -> #{wrap_union(names.map { |n| ":#{n}" }.join(" | "))}\n")
+          end
+          p.print("#{separator(overload)}(::int number) -> names?\n")
+          p.print("#{separator(overload)}...\n")
+          p.outdent
+          mid_line(initial, p)
+          p.print("def self.resolve:\n")
+          p.indent
+          overload = [true]
+          enum.values.each { |v| p.print("#{separator(overload)}(:#{v.name} name) -> #{v.number}\n") }
+          p.print("#{separator(overload)}(::Symbol name) -> numbers?\n")
+          p.print("#{separator(overload)}...\n")
+          p.outdent
+          mid_line(initial, p)
+          p.print("type names = #{enum.values.map { |v| ":#{v.name}" }.join(" | ")}\n")
+          mid_line(initial, p)
+          p.print("type strings = #{enum.values.map { |v| "\"#{v.name}\"" }.join(" | ")}\n")
+          mid_line(initial, p)
+          p.print("type numbers = #{by_number.keys.join(" | ")}\n")
+          p.outdent
+          p.print("end\n")
+        end
+
+        def field(p, field, path)
+          comment(p, path)
+          deprecation(p, field)
+          read = read_type(field)
+          write = write_type(field)
+          if read == write
+            p.print("attr_accessor #{field.name}(): #{read}\n")
+          else
+            p.print("attr_reader #{field.name}(): #{read}\nattr_writer #{field.name}(): #{write}\n")
+          end
+          if !field.repeated? && field.message_type && WRAPPERS.include?(field.message_type.full_name)
+            wrapped = field.message_type.fields_by_number[1]
+            if wrapped
+              wrapped_read = optional(scalar_read(wrapped))
+              wrapped_write = optional(scalar_write(wrapped))
+              if wrapped_read == wrapped_write
+                p.print("attr_accessor #{field.name}_as_value(): #{wrapped_read}\n")
+              else
+                p.print("attr_reader #{field.name}_as_value(): #{wrapped_read}\n" \
+                  "attr_writer #{field.name}_as_value(): #{wrapped_write}\n")
+              end
+            end
+          end
+          if field.type == :enum
+            if field.repeated?
+              p.print("attr_reader #{field.name}_const(): ::Array[::Integer]\n")
+            else
+              p.print("attr_reader #{field.name}_const(): ::Integer\n")
+            end
+          end
+          p.print("def has_#{field.name}?: () -> bool\n") if field.presence?
+          p.print("def clear_#{field.name}: () -> void\n")
+        end
+
+        def oneof(p, oneof, path)
+          comment(p, path)
+          types = []
+          oneof.fields.each do |f|
+            t = scalar_read(f)
+            types << t unless types.include?(t)
+          end
+          p.print("attr_reader #{oneof.name}(): #{optional(types.join(" | "))}\n")
+          p.print("def has_#{oneof.name}?: () -> bool\n")
+          p.print("def clear_#{oneof.name}: () -> void\n")
+        end
+
+        def message(p, message, path)
+          comment(p, path)
+          deprecation(p, message)
+          p.print("class #{Naming.rubify_constant(message.name)} < ::Google::Protobuf::AbstractMessage\n")
+          p.indent
+          initial = [true]
+          message.nested_messages.each_with_index do |m, i|
+            next if m.map_entry?
+            mid_line(initial, p)
+            message(p, m, path + [3, i])
+          end
+          message.nested_enums.each_with_index do |e, i|
+            mid_line(initial, p)
+            enum(p, e, path + [4, i])
+          end
+          mid_line(initial, p)
+          p.print("include ::Google::Protobuf::_MessageClass[#{message_name(message)}]\n")
+          message.fields.each_with_index do |f, i|
+            mid_line(initial, p)
+            field(p, f, path + [2, i])
+          end
+          message.oneofs.each_with_index do |o, i|
+            mid_line(initial, p)
+            oneof(p, o, path + [8, i])
+          end
+          mid_line(initial, p)
+          p.print("type init_map = {\n")
+          p.indent
+          message.fields.each do |f|
+            type = init_type(f)
+            p.print("#{f.name}: #{type},\n\"#{f.name}\" => #{type},\n")
+          end
+          p.outdent
+          p.print("}\n")
+          mid_line(initial, p)
+          p.print("def initialize: (?init_map initial_value) -> void\n")
+          full = message.full_name
+          if !message.fields.empty? && full != "google.protobuf.ListValue" && full != "google.protobuf.Struct"
+            mid_line(initial, p)
+            p.print("def []:\n")
+            p.indent
+            overload = [true]
+            message.fields.each do |f|
+              p.print("#{separator(overload)}(\"#{f.name}\" name) -> #{wrap_union(read_type(f))}\n")
+            end
+            p.outdent
+            mid_line(initial, p)
+            p.print("def []=:\n")
+            p.indent
+            overload = [true]
+            message.fields.each do |f|
+              p.print("#{separator(overload)}(\"#{f.name}\" name, #{wrap_union(write_type(f))} value) -> void\n")
+            end
+            p.outdent
+          end
+          p.outdent
+          p.print("end\n")
+        end
+
+        def message_lookup(p, message, overload)
+          p.print("#{separator(overload)}(\"#{message.full_name}\" name) -> (::Google::Protobuf::Descriptor & " \
+            "::Google::Protobuf::_SpecificDescriptor[singleton(#{message_name(message)})])\n")
+          message.nested_messages.each { |m| message_lookup(p, m, overload) unless m.map_entry? }
+          message.nested_enums.each { |e| enum_lookup(p, e, overload) }
+        end
+
+        def enum_lookup(p, enum, overload)
+          p.print("#{separator(overload)}(\"#{enum.full_name}\" name) -> (::Google::Protobuf::EnumDescriptor & " \
+            "::Google::Protobuf::_SpecificEnumDescriptor[singleton(#{enum_name(enum)})])\n")
+        end
+
+        def lookup_override(p, file)
+          p.print("module Google\n")
+          p.indent
+          p.print("module Protobuf\n")
+          p.indent
+          p.print("class DescriptorPool\n")
+          p.indent
+          p.print("def lookup:\n")
+          p.indent
+          overload = [true]
+          file.messages.each { |m| message_lookup(p, m, overload) }
+          file.enums.each { |e| enum_lookup(p, e, overload) }
+          p.print("#{separator(overload)}...\n")
+          p.outdent
+          p.outdent
+          p.print("end\n")
+          p.outdent
+          p.print("end\n")
+          p.outdent
+          p.print("end\n")
+        end
+      end
+    end
+  end
+end