protostar 0.1.0.beta1

data/lib/protostar/schema/enum.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Schema
+    # An enum type
+    class Enum < Descriptor
+      # @return [File]
+      attr_reader :file
+      # @return [Message, nil]
+      attr_reader :containing_message
+      # @return [Array<EnumValue>] declaration order
+      attr_reader :values
+      # @return [Hash{Integer => EnumValue}] the first declared value wins for aliases
+      attr_reader :values_by_number
+      # @return [Hash{String => EnumValue}]
+      attr_reader :values_by_name
+      # @return [Array<Range>] inclusive
+      attr_reader :reserved_ranges
+      # @return [Array<String>]
+      attr_reader :reserved_names
+      # @return [Symbol, nil] declared `visibility`: :local or :export (edition 2024), nil when not declared
+      attr_reader :visibility
+
+      # @api private
+      def initialize(name:, full_name:, file:, containing_message:, index:)
+        @name = name
+        @full_name = full_name
+        @file = file
+        @containing_message = containing_message
+        @index = index
+        @reserved_ranges = Freezer::EMPTY_ARRAY
+        @reserved_names = Freezer::EMPTY_ARRAY
+        @visibility = nil
+      end
+
+      # @api private
+      def __values(values)
+        @values = values
+        @values_by_number = {}
+        @values_by_name = {}
+        values.each do |v|
+          @values_by_number[v.number] ||= v
+          @values_by_name[v.name] ||= v
+        end
+        @values_by_number.freeze
+        @values_by_name.freeze
+        self
+      end
+
+      # @param key [Integer, String, Symbol] a value number or name
+      # @return [EnumValue, nil]
+      def value(key)
+        key.is_a?(Integer) ? @values_by_number[key] : @values_by_name[key.to_s]
+      end
+
+      # @return [Boolean]
+      def allow_alias?
+        options.allow_alias?
+      end
+
+      # @return [Boolean] unknown numbers go to unknown fields (proto2, editions
+      #   `enum_type = CLOSED`) instead of being kept in the field (proto3, `OPEN`)
+      def closed?
+        @features.enum_type == :CLOSED
+      end
+
+      # @return [Boolean]
+      def open?
+        !closed?
+      end
+
+      # @return [Protostar::Google::Protobuf::EnumDescriptorProto]
+      def to_proto
+        Proto::Writer.enum(self)
+      end
+    end
+
+    # A value of an enum. Its {#full_name} lives in the enum's enclosing scope,
+    # as in protoc: value `FOO` of `pkg.Color` is `pkg.FOO`.
+    class EnumValue < Descriptor
+      # @return [Integer]
+      attr_reader :number
+      # @return [Enum]
+      attr_reader :enum
+
+      # @api private
+      def initialize(name:, full_name:, number:, enum:, index:)
+        @name = name
+        @full_name = full_name
+        @number = number
+        @enum = enum
+        @index = index
+      end
+
+      # @return [File]
+      def file
+        @enum.file
+      end
+
+      # @return [Protostar::Google::Protobuf::EnumValueDescriptorProto]
+      def to_proto
+        Proto::Writer.enum_value(self)
+      end
+    end
+  end
+end

data/lib/protostar/schema/extension_range.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Schema
+    # One `extensions` declaration of a message, with its options and features
+    class ExtensionRange < Descriptor
+      # @return [Message]
+      attr_reader :containing_message
+      # @return [Range] inclusive
+      attr_reader :range
+
+      # @api private
+      def initialize(containing_message:, index:, range:)
+        @containing_message = containing_message
+        @index = index
+        @range = range
+        @name = "#{range.begin}..#{range.end}"
+        @full_name = "#{containing_message.full_name}.extensions(#{@name})"
+      end
+
+      # @return [File]
+      def file
+        @containing_message.file
+      end
+
+      # @return [Integer] first extension number, inclusive
+      def start
+        @range.begin
+      end
+
+      # @return [Integer] last extension number, inclusive
+      def end
+        @range.end
+      end
+    end
+  end
+end

data/lib/protostar/schema/features.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Schema
+    # Resolved editions features of a descriptor. proto2 and proto3 files are
+    # resolved as the editions EDITION_PROTO2 and EDITION_PROTO3, the way protoc
+    # does internally, so every descriptor has a complete set.
+    #
+    # Custom (extension) features such as `pb.cpp` are carried in {#extensions}
+    # as merged explicit values; their defaults are not known to this model.
+    class Features
+      # The Edition enum from descriptor.proto (lines 45-82)
+      EDITIONS = {
+        EDITION_UNKNOWN: 0,
+        EDITION_LEGACY: 900,
+        EDITION_PROTO2: 998,
+        EDITION_PROTO3: 999,
+        EDITION_2023: 1000,
+        EDITION_2024: 1001,
+        EDITION_2026: 1002,
+        EDITION_UNSTABLE: 9999,
+        EDITION_1_TEST_ONLY: 1,
+        EDITION_2_TEST_ONLY: 2,
+        EDITION_99997_TEST_ONLY: 99997,
+        EDITION_99998_TEST_ONLY: 99998,
+        EDITION_99999_TEST_ONLY: 99999,
+        EDITION_MAX: 0x7FFFFFFF
+      }.freeze
+
+      # Edition numbers to their enum names
+      EDITION_NAMES = EDITIONS.invert.freeze
+
+      # The `edition_defaults` annotations on FeatureSet in descriptor.proto,
+      # as [edition, value] pairs in ascending edition order. A feature takes the
+      # value of the last pair whose edition is at or before the file's edition.
+      DEFAULTS = {
+        # descriptor.proto lines 1074-1076
+        field_presence: [[:EDITION_LEGACY, :EXPLICIT], [:EDITION_PROTO3, :IMPLICIT], [:EDITION_2023, :EXPLICIT]],
+        # lines 1091-1092
+        enum_type: [[:EDITION_LEGACY, :CLOSED], [:EDITION_PROTO3, :OPEN]],
+        # lines 1107-1108
+        repeated_field_encoding: [[:EDITION_LEGACY, :EXPANDED], [:EDITION_PROTO3, :PACKED]],
+        # lines 1124-1125
+        utf8_validation: [[:EDITION_LEGACY, :NONE], [:EDITION_PROTO3, :VERIFY]],
+        # line 1140
+        message_encoding: [[:EDITION_LEGACY, :LENGTH_PREFIXED]],
+        # lines 1156-1157
+        json_format: [[:EDITION_LEGACY, :LEGACY_BEST_EFFORT], [:EDITION_PROTO3, :ALLOW]],
+        # lines 1180-1182
+        enforce_naming_style: [[:EDITION_LEGACY, :STYLE_LEGACY], [:EDITION_2024, :STYLE2024], [:EDITION_2026, :STYLE2026]],
+        # lines 1212-1214
+        default_symbol_visibility: [[:EDITION_LEGACY, :EXPORT_ALL], [:EDITION_2024, :EXPORT_TOP_LEVEL], [:EDITION_2026, :STRICT]],
+        # lines 1241-1245
+        enforce_proto_limits: [[:EDITION_LEGACY, :LEGACY_NO_EXPLICIT_LIMITS], [:EDITION_2026, :PROTO_LIMITS2026]]
+      }.transform_values { |pairs| pairs.map(&:freeze).freeze }.freeze
+
+      # Names of the core features, in FeatureSet field number order
+      NAMES = DEFAULTS.keys.freeze
+
+      # @param edition [Symbol, Integer] an Edition enum name or number
+      # @return [Integer]
+      def self.edition_number(edition)
+        return edition if edition.is_a?(Integer)
+        EDITIONS.fetch(edition) { raise Error, "unknown edition #{edition.inspect}" }
+      end
+
+      # The defaults for an edition, as protoc computes them from descriptor.proto
+      # @param edition [Symbol, Integer]
+      # @return [Features]
+      def self.defaults(edition)
+        number = edition_number(edition)
+        values = DEFAULTS.transform_values do |pairs|
+          pick = pairs.reverse_each.find { |(ed, _)| EDITIONS.fetch(ed) <= number }
+          raise Error, "no feature defaults for edition #{edition.inspect}" unless pick
+          pick.last
+        end
+        new(values, Freezer::EMPTY_HASH)
+      end
+
+      # @return [Hash{Field => MessageValue}] merged explicit custom features by extension
+      attr_reader :extensions
+
+      # @api private
+      def initialize(values, extensions)
+        @values = values.freeze
+        @extensions = extensions
+        NAMES.each { |name| instance_variable_set(:"@#{name}", values.fetch(name)) }
+        @hash = [@values, @extensions].hash
+        freeze
+      end
+
+      # @!attribute [r] field_presence
+      #   @return [Symbol] :EXPLICIT, :IMPLICIT or :LEGACY_REQUIRED
+      # @!attribute [r] enum_type
+      #   @return [Symbol] :OPEN or :CLOSED
+      # @!attribute [r] repeated_field_encoding
+      #   @return [Symbol] :PACKED or :EXPANDED
+      # @!attribute [r] utf8_validation
+      #   @return [Symbol] :VERIFY or :NONE
+      # @!attribute [r] message_encoding
+      #   @return [Symbol] :LENGTH_PREFIXED or :DELIMITED
+      # @!attribute [r] json_format
+      #   @return [Symbol] :ALLOW or :LEGACY_BEST_EFFORT
+      # @!attribute [r] enforce_naming_style
+      #   @return [Symbol]
+      # @!attribute [r] default_symbol_visibility
+      #   @return [Symbol]
+      # @!attribute [r] enforce_proto_limits
+      #   @return [Symbol]
+      attr_reader :field_presence, :enum_type, :repeated_field_encoding, :utf8_validation, :message_encoding,
+        :json_format, :enforce_naming_style, :default_symbol_visibility, :enforce_proto_limits
+
+      # Overlays a declared `features` option (a FeatureSet) on these features
+      # @param declared [MessageValue, nil]
+      # @return [Features] self when the overlay changes nothing
+      def merge(declared)
+        return self if declared.nil? || declared.empty?
+        values = @values
+        declared.fields.each do |key, value|
+          next unless NAMES.include?(key) && value.is_a?(Symbol)
+          values = values.merge(key => value) unless values[key] == value
+        end
+        extensions = MessageValue.merge_values(@extensions, declared.extensions)
+        return self if values.equal?(@values) && extensions.equal?(@extensions)
+        Features.new(values, extensions)
+      end
+
+      # @param values [Hash{Symbol => Symbol}] core features to override
+      # @return [Features] self when nothing changes
+      def with(**values)
+        return self if values.all? { |k, v| @values[k] == v }
+        Features.new(@values.merge(values), @extensions)
+      end
+
+      # @return [Hash{Symbol => Symbol}] the core features by name
+      def to_h
+        @values
+      end
+
+      def ==(other)
+        other.is_a?(Features) && other.to_h == @values && other.extensions == @extensions
+      end
+      alias_method :eql?, :==
+
+      attr_reader :hash
+
+      def inspect
+        custom = @extensions.map { |f, v| " (#{f.full_name}): #{v.inspect}" }.join
+        "#<#{self.class.name} #{@values.inspect}#{custom}>"
+      end
+    end
+  end
+end

data/lib/protostar/schema/field.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Schema
+    # A field of a message, or an extension
+    class Field < Descriptor
+      # FieldDescriptorProto.Type names to the short type symbols
+      TYPES = {
+        TYPE_DOUBLE: :double, TYPE_FLOAT: :float, TYPE_INT64: :int64, TYPE_UINT64: :uint64,
+        TYPE_INT32: :int32, TYPE_FIXED64: :fixed64, TYPE_FIXED32: :fixed32, TYPE_BOOL: :bool,
+        TYPE_STRING: :string, TYPE_GROUP: :group, TYPE_MESSAGE: :message, TYPE_BYTES: :bytes,
+        TYPE_UINT32: :uint32, TYPE_ENUM: :enum, TYPE_SFIXED32: :sfixed32, TYPE_SFIXED64: :sfixed64,
+        TYPE_SINT32: :sint32, TYPE_SINT64: :sint64
+      }.freeze
+
+      # FieldDescriptorProto.Label names to the short label symbols
+      LABELS = {LABEL_OPTIONAL: :optional, LABEL_REQUIRED: :required, LABEL_REPEATED: :repeated}.freeze
+
+      # @api private
+      PROTO_TYPES = TYPES.invert.freeze
+      # @api private
+      PROTO_LABELS = LABELS.invert.freeze
+
+      # Wire type of a single, unpacked value of each type
+      WIRE_TYPES = {
+        double: 1, float: 5, int64: 0, uint64: 0, int32: 0, fixed64: 1, fixed32: 5, bool: 0,
+        string: 2, group: 3, message: 2, bytes: 2, uint32: 0, enum: 0, sfixed32: 5, sfixed64: 1,
+        sint32: 0, sint64: 0
+      }.freeze
+
+      # The implicit default of each scalar type
+      ZERO = {
+        double: 0.0, float: 0.0, int64: 0, uint64: 0, int32: 0, fixed64: 0, fixed32: 0, bool: false,
+        string: "".encode(Encoding::UTF_8).freeze, bytes: "".b.freeze, uint32: 0, sfixed32: 0,
+        sfixed64: 0, sint32: 0, sint64: 0
+      }.freeze
+
+      UNPACKABLE = %i[string bytes message group].freeze
+
+      # @return [Integer]
+      attr_reader :number
+      # @return [Symbol] :optional, :required or :repeated, with editions
+      #   `LEGACY_REQUIRED` presence reported as :required
+      attr_reader :label
+      # @return [Symbol] :int32, :string, :message, ... with editions
+      #   `DELIMITED` message fields reported as :group, as protoc does
+      attr_reader :type
+      # @return [String, nil] full name of the message or enum type, no leading dot
+      attr_reader :type_name
+      # @return [Message, nil]
+      attr_reader :message_type
+      # @return [Enum, nil]
+      attr_reader :enum_type
+      # @return [Object, nil] the declared default parsed to a Ruby value
+      #   (Integer, Float, true/false, String, binary String, or Symbol for enums)
+      attr_reader :default_value
+      # @return [Object, nil] {#default_value}, or the type's implicit default:
+      #   zero, false, an empty String, the first value's name for an enum, nil for messages.
+      #   For repeated fields this is the default of a single element.
+      attr_reader :default
+      # @return [String]
+      attr_reader :json_name
+      # @return [Oneof, nil] the containing oneof, synthetic ones included
+      attr_reader :oneof
+      # @return [Message, nil] for an extension, the extended message
+      attr_reader :extendee
+      # @return [Message, nil] the message holding the field; for an extension the
+      #   message it was declared in, or nil when declared at file level
+      attr_reader :containing_message
+      # @return [File]
+      attr_reader :file
+
+      # @api private
+      def initialize(name:, full_name:, number:, label:, type:, type_name:, extendee_name:, raw_default:, json_name:,
+        proto3_optional:, extension:, containing_message:, file:, index:)
+        @name = name
+        @full_name = full_name
+        @number = number
+        @declared_label = label
+        @declared_type = type
+        @label = label
+        @type = type
+        @type_name = type_name
+        @extendee_name = extendee_name
+        @raw_default = raw_default
+        @json_name = json_name
+        @proto3_optional = proto3_optional
+        @extension = extension
+        @containing_message = containing_message
+        @file = file
+        @index = index
+      end
+
+      # @api private
+      # @return [String, nil] the default as protoc stores it in `default_value`
+      attr_reader :raw_default
+      # @api private
+      # @return [String, nil] the extendee as written, until it is resolved
+      attr_reader :extendee_name
+      # @api private
+      # @return [Symbol, nil] the label as declared: :repeated, :optional or :required,
+      #   before editions features turn `LEGACY_REQUIRED` into :required
+      attr_reader :declared_label
+      # @api private
+      # @return [Symbol, nil] the type as declared, before editions features turn
+      #   `DELIMITED` message fields into :group; nil while a type name is unresolved
+      attr_reader :declared_type
+
+      # @return [Boolean]
+      def proto3_optional?
+        @proto3_optional
+      end
+
+      # @return [Boolean]
+      def extension?
+        @extension
+      end
+
+      # @return [Oneof, nil] the containing oneof unless it is synthetic
+      def real_oneof
+        @oneof unless @oneof.nil? || @oneof.synthetic?
+      end
+
+      # @return [Boolean]
+      def repeated?
+        @label == :repeated
+      end
+
+      # @return [Boolean]
+      def required?
+        @label == :required
+      end
+
+      # @return [Boolean]
+      def optional?
+        @label == :optional
+      end
+
+      # @return [Boolean] a `map<K, V>` field: repeated, of a map entry message type
+      def map?
+        @label == :repeated && !@message_type.nil? && @message_type.map_entry?
+      end
+
+      # @return [Field, nil] the key field of a map field's entry
+      def map_key
+        @message_type.fields_by_number[1] if map?
+      end
+
+      # @return [Field, nil] the value field of a map field's entry
+      def map_value
+        @message_type.fields_by_number[2] if map?
+      end
+
+      # @return [Boolean] not a message or group; enums count as scalars
+      def scalar?
+        @type != :message && @type != :group
+      end
+
+      # @return [Boolean] repeated and of a type that can be packed
+      def packable?
+        @label == :repeated && !UNPACKABLE.include?(@type)
+      end
+
+      # @return [Boolean] whether repeated values are written packed. Resolved
+      #   through features: proto2 defaults to expanded, proto3 to packed, editions
+      #   follow `repeated_field_encoding`, and a legacy `packed` option wins.
+      def packed?
+        packable? && @features.repeated_field_encoding == :PACKED
+      end
+
+      # @return [Boolean] explicit presence (has-bits): singular fields that are
+      #   messages, extensions, oneof members, or not `IMPLICIT` by features
+      def presence?
+        return false if @label == :repeated
+        @type == :message || @type == :group || @extension || !@oneof.nil? ||
+          @features.field_presence != :IMPLICIT
+      end
+
+      # @return [Boolean] group, or editions `message_encoding = DELIMITED`
+      def delimited?
+        @type == :group
+      end
+
+      # @return [Integer] the wire type of one unpacked value
+      def wire_type
+        WIRE_TYPES.fetch(@type)
+      end
+
+      # @return [Boolean] whether string values must be valid UTF-8 when parsed
+      def utf8_validation?
+        @type == :string && @features.utf8_validation == :VERIFY
+      end
+
+      # @param default_json_names [Boolean] see {File#to_proto}
+      # @return [Protostar::Google::Protobuf::FieldDescriptorProto]
+      def to_proto(default_json_names: true)
+        Proto::Writer.field(self, default_json_names)
+      end
+    end
+  end
+end