field_struct 0.15.0

data/lib/field_struct/model_name.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module FieldStruct
+  # Minimal ActiveModel::Name-shaped value for {Base.model_name}.
+  #
+  # We mirror only what Rails-adjacent callers commonly reach for:
+  # +name+, +singular+, +plural+, +element+, and string coercion.
+  # No ActiveModel code is reused; pluralization is naive +s+-suffix
+  # English. If a richer Name is needed, a downstream gem can build on
+  # this without changing the surface.
+  class ModelName
+    # @return [String] the fully-qualified class name (or "" for anonymous classes)
+    attr_reader :name
+
+    # @return [String] last segment, snake_case (e.g. "user_account")
+    attr_reader :singular
+
+    # @return [String] naive +s+-suffixed plural of {#singular}
+    attr_reader :plural
+
+    # @return [String] same as {#singular} (the AM convention for last segment)
+    attr_reader :element
+
+    # @param class_name [String, nil]
+    def initialize(class_name)
+      @name = class_name.to_s
+      base = @name.split('::').last.to_s
+      @element = camel_to_snake(base)
+      @singular = @element
+      @plural = "#{@element}s"
+    end
+
+    # @return [String]
+    def to_s
+      @name
+    end
+
+    alias to_str to_s
+
+    private
+
+    # @param str [String] a bare class name
+    # @return [String] its snake_case form
+    def camel_to_snake(str)
+      str.gsub(/([a-z\d])([A-Z])/, '\\1_\\2').gsub(/([A-Z]+)([A-Z][a-z])/, '\\1_\\2').downcase
+    end
+  end
+end

data/lib/field_struct/rbs.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+module FieldStruct
+  # Generates RBS type signatures for the *generated* instance surface of
+  # user-defined {FieldStruct::Base} subclasses — the per-field accessors the
+  # +field+ DSL defines dynamically.
+  #
+  # Sord generates +sig/field_struct.rbs+ from the library's static source, so
+  # it covers {Base}, {Types}, {Registry}, … but it can never see +User#name+
+  # or +User#age=+: those methods don't exist until a consumer declares the
+  # fields. This is the deferred "track 2" of the plan's RBS strategy (D13) —
+  # walk a subclass's {Metadata} and emit signatures for its accessors so
+  # downstream Steep / Solargraph can type-check code that touches them.
+  #
+  #   class User < FieldStruct::Base
+  #     required :name, :string
+  #     optional :age,  :integer
+  #   end
+  #
+  #   puts FieldStruct::RBS.generate(User)
+  #   # # Generated by FieldStruct::RBS. ...
+  #   # class User < ::FieldStruct::Base
+  #   #   attr_reader name: ::String
+  #   #   def name=: (::String? value) -> ::String?
+  #   #
+  #   #   attr_reader age: ::Integer?
+  #   #   def age=: (::Integer? value) -> ::Integer?
+  #   # end
+  #
+  # Design choices:
+  #
+  # * **Types describe a valid instance.** The reader type is the field's
+  #   {Types::Base#ruby_type} (or an override, below). Nullability follows
+  #   {Field#required?}: required → +T+, optional → +T?+. An invalid
+  #   instance — a required field left unset, or a +:keep_raw+ coercion
+  #   failure holding the raw input — can hold other values; check +valid?+
+  #   before trusting the signature. The generated header says so.
+  # * **Writer** is +(T? value) -> T?+: the runtime setter accepts +nil+ and
+  #   returns the coerced value. Loose input the type would coerce
+  #   (+user.age = "30"+) is valid Ruby but a type error to Steep — cast or
+  #   coerce at the boundary.
+  # * **Generic arguments** are filled in: arrays as +::Array[Element]+
+  #   (a scalar element as +Element?+, since a valid instance can hold nil
+  #   elements; a nested element stays non-nil, since nil makes it invalid),
+  #   unions as +(A | B)+ (a boolean member as +bool+, a member's own
+  #   {Types::Base#rbs_type} first), nested structs by qualified name; an
+  #   anonymous nested class raises +ArgumentError+. A custom type whose +ruby_type+ is a bare generic
+  #   class (+::Hash+) gets +untyped+ arguments unless it declares
+  #   {Types::Base#rbs_type}.
+  # * **Anything-valued fields** (+:value+, or a union with a +:value+
+  #   member) are +untyped+ — reader and writer, never +untyped?+.
+  # * **Overrides:** a field's +rbs_type:+ option, then the type's
+  #   {Types::Base#rbs_type}, replace the derived type +T+ verbatim;
+  #   nullability is still added for optional fields and writers.
+  # * **+new+ / +initialize+** are inherited from {Base}, which already
+  #   accepts +User.new(name: ...)+.
+  #
+  # Each call emits one class. Referenced types (nested structs, array
+  # elements) appear as qualified names (+::Address+) — generate RBS for those
+  # classes too so the references resolve. {.type_for} exposes the per-field
+  # mapping for other generators.
+  module RBS
+    # The pair a +:boolean+ field's +ruby_type+ returns, rendered as +bool+.
+    # @return [Array<Class>]
+    BOOL_CLASSES = [TrueClass, FalseClass].freeze
+    private_constant :BOOL_CLASSES
+
+    # Comment lines opening every {.generate} result: the contract the
+    # signatures hold to.
+    # @return [String]
+    HEADER = <<~RBS
+      # Generated by FieldStruct::RBS. Types describe a valid instance: an
+      # invalid one (a required field left unset, or a :keep_raw coercion
+      # failure holding the raw input) can hold other values. Check valid?.
+    RBS
+    private_constant :HEADER
+
+    # Ruby classes RBS declares with type parameters, and how many. A bare
+    # +ruby_type+ naming one of these is emitted with +untyped+ arguments,
+    # since RBS rejects a generic class without them.
+    # @return [Hash{Class=>Integer}]
+    GENERIC_ARITY = {::Array => 1, ::Hash => 2, ::Range => 1}.freeze
+    private_constant :GENERIC_ARITY
+
+    # Generate RBS source for a single FieldStruct subclass.
+    #
+    # @param klass [Class<FieldStruct::Base>]
+    # @return [String] RBS declaring the class (wrapped in its module nesting)
+    #   and a typed reader and writer for every field it declares, after a
+    #   comment header stating that the types describe a valid instance
+    # @raise [ArgumentError] when +klass+ is not a named {FieldStruct::Base}
+    #   subclass
+    def self.generate(klass)
+      unless klass.is_a?(::Class) && klass < FieldStruct::Base
+        raise ArgumentError,
+          "FieldStruct::RBS.generate expects a FieldStruct::Base subclass, got #{klass.inspect}"
+      end
+      raise ArgumentError, 'cannot generate RBS for an anonymous class' unless klass.name
+
+      HEADER + wrap_namespace(klass.name, class_block(klass))
+    end
+
+    # The RBS type of one field's value, as {.generate} emits it — for other
+    # generators (e.g. one typing a method that takes or returns the field)
+    # that need the same mapping:
+    #
+    #   FieldStruct::RBS.type_for(Order.metadata[:items])
+    #   # => "::Array[::LineItem]?"
+    #   FieldStruct::RBS.type_for(Order.metadata[:items], nullable: false)
+    #   # => "::Array[::LineItem]"
+    #
+    # The type comes from the field's +rbs_type:+ option, else its type's
+    # {Types::Base#rbs_type}, else its {Types::Base#ruby_type} with generic
+    # arguments filled in. Qualified names (+::LineItem+) assume the
+    # referenced classes get RBS too.
+    #
+    # @param field [Field] a declared field, e.g. +Order.metadata[:items]+
+    # @param nullable [Boolean, nil] append +?+ (the reader type of an
+    #   optional field, and every writer's); +nil+, the default, means
+    #   +!field.required?+. Never applied to +untyped+, which already
+    #   admits +nil+.
+    # @return [String] an RBS type expression
+    # @raise [ArgumentError] when +field+ is not a {Field}
+    def self.type_for(field, nullable: nil)
+      unless field.is_a?(FieldStruct::Field)
+        raise ArgumentError, 'FieldStruct::RBS.type_for expects a FieldStruct::Field ' \
+                             "(e.g. User.metadata[:name]), got #{field.inspect}"
+      end
+
+      nullable = !field.required? if nullable.nil?
+      base = override_expression(field.rbs_type || field.type_instance.rbs_type) ||
+        expression_for(field.type_instance, field.options)
+      nullable ? optional(base) : base
+    end
+
+    # Build the +class ... end+ block (unindented, no surrounding modules).
+    #
+    # @param klass [Class<FieldStruct::Base>]
+    # @return [String]
+    def self.class_block(klass)
+      simple = klass.name.split('::').last
+      lines = ["class #{simple} < ::#{klass.superclass.name}"]
+      own_fields(klass).each_with_index do |field, index|
+        writer = type_for(field, nullable: true)
+        lines << '' unless index.zero?
+        lines << "  attr_reader #{field.name}: #{type_for(field)}"
+        lines << "  def #{field.name}=: (#{writer} value) -> #{writer}"
+      end
+      lines << 'end'
+      lines.join("\n")
+    end
+    private_class_method :class_block
+
+    # Fields declared on +klass+ itself — inherited fields (the same {Field}
+    # objects merged in at inheritance time) belong to the parent's RBS.
+    #
+    # @param klass [Class<FieldStruct::Base>]
+    # @return [Array<Field>]
+    def self.own_fields(klass)
+      parent = klass.superclass
+      parent_meta = parent.respond_to?(:metadata) ? parent.metadata : nil
+      klass.metadata.reject { |field| parent_meta && parent_meta[field.name].equal?(field) }
+    end
+    private_class_method :own_fields
+
+    # An override, parenthesized when it is a union, intersection or proc
+    # type, so a trailing +?+ applies to the whole of it.
+    #
+    # @param rbs [String, nil] a field's +rbs_type:+ or a type's +rbs_type+
+    # @return [String, nil] +nil+ when there is no override
+    def self.override_expression(rbs)
+      return nil if rbs.nil?
+
+      rbs = rbs.strip
+      return rbs if wrapped?(rbs)
+
+      rbs.match?(/[|&^]/) ? "(#{rbs})" : rbs
+    end
+    private_class_method :override_expression
+
+    # @param rbs [String] a stripped RBS type expression
+    # @return [Boolean] whether one parenthesized group spans all of +rbs+
+    #   (optionally followed by +?+), so wrapping it again adds nothing
+    def self.wrapped?(rbs)
+      return false unless rbs.start_with?('(')
+
+      depth = 0
+      rbs.each_char.with_index do |char, index|
+        depth += 1 if char == '('
+        depth -= 1 if char == ')'
+        return rbs[(index + 1)..].then { |rest| rest.empty? || rest == '?' } if depth.zero?
+      end
+      false
+    end
+    private_class_method :wrapped?
+
+    # @param base [String] an RBS type expression
+    # @return [String] +base+ made nullable, unless it already admits +nil+
+    def self.optional(base)
+      return base if base == 'untyped' || base.end_with?('?')
+
+      "#{base}?"
+    end
+    private_class_method :optional
+
+    # Map a type instance (plus its field options, needed for arrays) to an
+    # RBS type expression.
+    #
+    # @param type_instance [Types::Base]
+    # @param options [Hash{Symbol=>Object, nil}]
+    # @return [String]
+    def self.expression_for(type_instance, options)
+      return "::Array[#{element_type(options[:of_type])}]" if type_instance.is_a?(FieldStruct::Types::Array)
+      return union_expression(type_instance) if type_instance.is_a?(FieldStruct::Types::Union)
+
+      ruby_type = type_instance.ruby_type
+      classes = ruby_type.is_a?(::Array) ? ruby_type : [ruby_type]
+      mapped = classes_to_rbs(classes)
+      return 'untyped' if mapped.include?('untyped')
+
+      mapped.one? ? mapped.first : "(#{mapped.join(" | ")})"
+    end
+    private_class_method :expression_for
+
+    # A union as its members' types, each member's own +rbs_type+ first.
+    #
+    # @param union [Types::Union]
+    # @return [String] +untyped+ when any member is
+    def self.union_expression(union)
+      members = union.member_types.map { |member| override_expression(member.rbs_type) || expression_for(member, {}) }
+      return 'untyped' if members.include?('untyped')
+
+      members = members.uniq
+      members.one? ? members.first : "(#{members.join(" | ")})"
+    end
+    private_class_method :union_expression
+
+    # @param classes [Array<Class>] a {Types::Base#ruby_type}, as a list
+    # @return [Array<String>] one RBS type per class, with +TrueClass+ /
+    #   +FalseClass+ together collapsed to +bool+ where the pair appears
+    def self.classes_to_rbs(classes)
+      bool = BOOL_CLASSES.all? { |klass| classes.include?(klass) }
+      classes.map { |klass| bool && BOOL_CLASSES.include?(klass) ? 'bool' : class_to_rbs(klass) }.uniq
+    end
+    private_class_method :classes_to_rbs
+
+    # The element type of an array field, derived from its +:of_type+ (a
+    # +Types::Base+ subclass for stock types, or a built instance for
+    # parameterized ones like {Types::Nested}).
+    #
+    # @param of_type [Class, Types::Base, nil]
+    # @return [String]
+    def self.element_type(of_type)
+      return 'untyped' if of_type.nil?
+
+      instance = of_type.is_a?(::Class) ? of_type.new : of_type
+      expression = override_expression(instance.rbs_type) || expression_for(instance, {})
+      # A valid instance may hold nil scalar elements; a nil nested element
+      # fails validation, so nested elements stay non-nil.
+      instance.is_a?(FieldStruct::Types::Nested) ? expression : optional(expression)
+    end
+    private_class_method :element_type
+
+    # @param klass [Class] a Ruby class from a {Types::Base#ruby_type}
+    # @return [String] qualified RBS name (with +untyped+ type arguments for
+    #   a generic class), or +untyped+ for the value type's +::Object+
+    def self.class_to_rbs(klass)
+      return 'untyped' if klass == ::Object
+      raise ArgumentError, 'FieldStruct::RBS cannot name an anonymous class; assign it to a constant' if klass.name.nil?
+
+      arity = GENERIC_ARITY[klass]
+      return "::#{klass.name}" unless arity
+
+      "::#{klass.name}[#{Array.new(arity, "untyped").join(", ")}]"
+    end
+    private_class_method :class_to_rbs
+
+    # Wrap an inner block in the +module ... end+ nesting implied by a
+    # qualified class name, indenting two spaces per level.
+    #
+    # @param full_name [String] e.g. +"Acme::Order"+
+    # @param inner [String] the class block
+    # @return [String] RBS source ending in a trailing newline
+    def self.wrap_namespace(full_name, inner)
+      modules = full_name.split('::')[0...-1]
+      block = inner
+      modules.reverse_each { |mod| block = "module #{mod}\n#{indent(block)}\nend" }
+      "#{block}\n"
+    end
+    private_class_method :wrap_namespace
+
+    # @param text [String]
+    # @return [String] +text+ with every non-blank line indented two spaces
+    def self.indent(text)
+      text.split("\n", -1).map { |line| line.empty? ? line : "  #{line}" }.join("\n")
+    end
+    private_class_method :indent
+  end
+end

data/lib/field_struct/registry.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module FieldStruct
+  # Name → type-class map with optional parent fallback.
+  #
+  # Holds the resolution table that maps symbolic type names (`:string`,
+  # `:integer`, …) to the {Types} classes that implement them. A namespace
+  # can build its own registry parented to the base ({FieldStruct.types})
+  # to extend or override the default set without mutating it.
+  class Registry
+    # @return [Registry, nil] the parent registry, or +nil+ for an unparented one
+    attr_reader :parent
+
+    # @param parent [Registry, nil] the registry to fall back to when a name
+    #   isn't found locally
+    def initialize(parent = nil)
+      @parent = parent
+      @types = {}
+    end
+
+    # Register a type class — or an alias to an already-registered name.
+    #
+    #   registry.register(:integer, MyInteger)        # type class
+    #   registry.register(:decimal, :big_decimal)     # alias (resolved now)
+    #
+    # Aliases are eagerly resolved through {#lookup}, so the alias target
+    # must already be registered (locally or in a parent). A later
+    # registration of the same name overwrites silently — this is the
+    # mechanism that lets a namespace registry shadow a parent's type.
+    #
+    # @param name [Symbol, String] the name to register
+    # @param target [Class, Symbol] a type class, or an existing registered name
+    # @return [self]
+    # @raise [KeyError] when +target+ is a Symbol that isn't registered yet
+    def register(name, target)
+      type_class = target.is_a?(::Symbol) ? lookup(target) : target
+      @types[name.to_sym] = type_class
+      self
+    end
+
+    # Resolve a name to its type class, walking the parent chain.
+    #
+    # @param name [Symbol, String]
+    # @return [Class] the type class
+    # @raise [KeyError] when the name isn't registered locally or via the parent chain
+    def lookup(name)
+      key = name.to_sym
+      return @types[key] if @types.key?(key)
+      return @parent.lookup(key) if @parent
+
+      raise ::KeyError, "no FieldStruct type registered for #{name.inspect}"
+    end
+
+    # Whether the name resolves to anything (locally or via the parent chain).
+    #
+    # @param name [Symbol, String]
+    # @return [Boolean]
+    def key?(name)
+      key = name.to_sym
+      return true if @types.key?(key)
+
+      !@parent.nil? && @parent.key?(key)
+    end
+
+    # Every distinct type class resolvable through this registry, including
+    # those inherited from the parent chain. Local entries come first;
+    # duplicates (e.g. an alias pointing at an already-listed class, or a
+    # parent class also registered locally) are removed.
+    #
+    # @return [Array<Class>] deduplicated, local-first
+    def type_classes
+      own = @types.values
+      (@parent ? own + @parent.type_classes : own).uniq
+    end
+
+    # @return [String] one-line summary of the locally-registered names
+    #   (does not enumerate the parent chain), with a +parent+ marker
+    #   when the registry has one
+    def inspect
+      parts = ["types=#{@types.keys.inspect}"]
+      parts << 'parent' if @parent
+      "#<#{FieldStruct.inspect_namespace}::Registry #{parts.join(" ")}>"
+    end
+  end
+end