field_struct 0.15.0

data/lib/field_struct/scaffold.rb

@@ -0,0 +1,331 @@
+# frozen_string_literal: true
+
+module FieldStruct
+  # Scaffolds FieldStruct class source from one or more JSON example objects.
+  #
+  # The goal is a *working prototype* you then refine by hand — the generator
+  # is deliberately conservative about types and never guesses past the
+  # evidence. Pass a single object to seed the shape, or an array of
+  # same-shape objects to gather more signal (empty fields get resolved from
+  # other samples, presence drives required/optional, and small repeated
+  # vocabularies surface as enum candidates). A single object is just the
+  # one-sample case of the same engine.
+  #
+  #   FieldStruct::Scaffold.from_json(<<~JSON, class_name: 'User')
+  #     {"name": "Al", "age": 30, "active": true}
+  #   JSON
+  #   # class User < FieldStruct::Base
+  #   #   required :name, :string
+  #   #   required :age, :integer
+  #   #   required :active, :boolean
+  #   # end
+  #
+  # Inference rules (conservative on purpose):
+  #
+  # * JSON object → a nested FieldStruct class (emitted before its parent).
+  # * JSON array → +:array, of: <element type>+ (element class for arrays of objects).
+  # * JSON +true+/+false+ → +:boolean+; integer → +:integer+; real → +:float+.
+  # * JSON string → +:string+ — *including numeric-looking strings* (an
+  #   +authorization_code+ must not become an Integer). Hints like "maybe
+  #   :big_decimal" are emitted as trailing comments, not committed types.
+  # * required when present and non-blank across *every* sample; else optional.
+  #
+  # The developer adds enums, descriptions, formats, and final scalar types;
+  # the comments point at where.
+  module Scaffold
+    # Matches an integer- or decimal-looking string (kept as +:string+, only hinted).
+    # @return [Regexp]
+    NUMERIC_STRING = /\A-?\d+(?:\.\d+)?\z/
+    # Most distinct repeated string values before a field is flagged as an enum candidate.
+    # @return [Integer]
+    ENUM_MAX_DISTINCT = 6
+    # Names a scaffolded attribute can't take (suffixed with +_field+): Ruby
+    # keywords, plus {Base::RESERVED_FIELD_NAMES}, which +field+ refuses.
+    #
+    # @return [Array<String>]
+    RESERVED = (%w[
+      BEGIN END alias and begin break case class def defined? do else elsif end
+      ensure false for if in module next nil not or redo rescue retry return self
+      super then true undef unless until when while yield __FILE__ __LINE__
+    ] + Base::RESERVED_FIELD_NAMES.map(&:to_s)).uniq.freeze
+
+    # Generate FieldStruct class source from JSON example(s).
+    #
+    # @param input [String, Hash{Object=>Object, nil}, Array<Hash{Object=>Object, nil}>] a JSON string (object or array
+    #   root), a parsed Hash, or an Array of same-shape Hashes
+    # @param class_name [String] the root class name
+    # @return [String] Ruby source defining the class and any nested classes
+    # @raise [ArgumentError] for an empty set or non-object samples
+    def self.from_json(input, class_name: 'Generated')
+      samples = normalize(input)
+      raise ArgumentError, 'no samples to scaffold from' if samples.empty?
+      raise ArgumentError, 'every sample must be a JSON object' unless samples.all?(::Hash)
+
+      classes = []
+      emit_object(class_name, samples, classes, [])
+      "#{classes.join("\n\n")}\n"
+    end
+
+    # @param input [String, Hash{Object=>Object, nil}, Array<Hash{Object=>Object, nil}>]
+    # @return [Array<Object>] the sample set (a lone object becomes a set of
+    #   one); {.from_json} checks every element is a Hash
+    def self.normalize(input)
+      data = input.is_a?(::String) ? Oj.load(input, mode: :strict) : input
+      case data
+      when ::Array then data
+      when ::Hash then [data]
+      else
+        raise ArgumentError, "expected a JSON object or array of objects, got #{data.class}"
+      end
+    end
+    private_class_method :normalize
+
+    # Build the class for +samples+ as +class_name+, appending nested classes
+    # to +classes+ first (post-order, so references resolve), and return the
+    # (deduplicated) class name used.
+    #
+    # @param class_name [String] the name wanted
+    # @param samples [Array<Hash{Object=>Object, nil}>]
+    # @param classes [Array<String>] class sources emitted so far (appended to)
+    # @param used [Array<String>] class names taken so far (appended to)
+    # @return [String]
+    def self.emit_object(class_name, samples, classes, used)
+      name = unique_name(class_name, used)
+      total = samples.length
+      mappings = {}
+      attrs = []
+      lines = ordered_keys(samples).map do |key|
+        # Two keys can normalize to one name ("fooBar"/"foo_bar"); suffix the
+        # later one so neither value is lost.
+        attr = unique_name(safe_attr(key), attrs)
+        mappings[attr] = key unless attr == key
+        field_line(attr, observe(samples, key), total, classes, used)
+      end
+      classes << build_class(name, mappings, lines)
+      name
+    end
+    private_class_method :emit_object
+
+    # @param samples [Array<Hash{Object=>Object, nil}>]
+    # @param key [Object] a sample key
+    # @return [Hash{Symbol=>Integer, Array<Object, nil>}] +{ present: Integer, values: Array }+
+    #   for +key+ across samples
+    def self.observe(samples, key)
+      present = samples.select { |sample| sample.key?(key) }
+      {present: present.length, values: present.map { |sample| sample[key] }}
+    end
+    private_class_method :observe
+
+    # @param attr [String] the attribute name
+    # @param obs [Hash{Symbol=>Integer, Array<Object, nil>}] from {.observe}
+    # @param total [Integer] the sample count
+    # @param classes [Array<String>] class sources emitted so far
+    # @param used [Array<String>] class names taken so far
+    # @return [String] the indented DSL line
+    def self.field_line(attr, obs, total, classes, used)
+      values = obs[:values]
+      non_nil = values.compact
+      missing = values.count(&:nil?) + values.count { |v| blank_string?(v) }
+      required = obs[:present] == total && missing.zero?
+      avail = availability_comment(obs[:present], total, missing)
+
+      type_part, hint = type_for(attr, non_nil, classes, used)
+      decorate("#{required ? "required" : "optional"} :#{attr}, #{type_part}", avail, hint)
+    end
+    private_class_method :field_line
+
+    # @param attr [String] the attribute name
+    # @param non_nil [Array<Object>] the attribute's non-nil sample values
+    # @param classes [Array<String>] class sources emitted so far
+    # @param used [Array<String>] class names taken so far
+    # @return [Array(String, String)] +[type_part, comment_hint]+
+    def self.type_for(attr, non_nil, classes, used)
+      if non_nil.any?(::Hash)
+        [emit_object(class_name_for(attr), non_nil.grep(::Hash), classes, used), nil]
+      elsif non_nil.any?(::Array)
+        of_part, hint = array_element(attr, non_nil.grep(::Array).flatten(1), classes, used)
+        [":array, of: #{of_part}", hint]
+      else
+        sym, hint = infer_scalar(non_nil)
+        [":#{sym}", hint]
+      end
+    end
+    private_class_method :type_for
+
+    # @param attr [String] the attribute name
+    # @param elements [Array<Object, nil>] every element of the attribute's arrays
+    # @param classes [Array<String>] class sources emitted so far
+    # @param used [Array<String>] class names taken so far
+    # @return [Array(String, String)] +of:+ value and a comment hint
+    def self.array_element(attr, elements, classes, used)
+      non_nil = elements.compact
+      return [':value', 'empty array(s) in samples — element type unknown'] if non_nil.empty?
+      return [emit_object(class_name_for(singularize(attr)), non_nil.grep(::Hash), classes, used), nil] \
+        if non_nil.any?(::Hash)
+
+      sym, hint = infer_scalar(non_nil)
+      [":#{sym}", hint]
+    end
+    private_class_method :array_element
+
+    # @param values [Array<Object>] non-nil scalar sample values
+    # @return [Array(Symbol, String)] inferred scalar type and a comment hint
+    def self.infer_scalar(values)
+      return [:string, 'always null/absent in samples — type unknown'] if values.empty?
+
+      kinds = values.map { |v| scalar_kind(v) }.uniq
+      return [:boolean, nil] if kinds == [:boolean]
+      return [:integer, nil] if kinds == [:integer]
+      return [:float, nil] if (kinds - %i[integer float]).empty?
+      return string_inference(values) if kinds == [:string]
+
+      [:value, "mixed types in samples (#{kinds.join(", ")}) — review"]
+    end
+    private_class_method :infer_scalar
+
+    # @param values [Array<String>]
+    # @return [Array(Symbol, String)] +:string+ and a comment hint
+    def self.string_inference(values)
+      non_empty = values.reject { |s| blank_string?(s) }
+      return [:string, 'always empty in samples — type unknown'] if non_empty.empty?
+
+      if non_empty.all? { |s| s.match?(NUMERIC_STRING) }
+        suggestion = non_empty.any? { |s| s.include?('.') } ? ':big_decimal' : ':integer'
+        return [:string, %(numeric-looking (e.g. "#{non_empty.first}") — #{suggestion}? or keep :string if an id/code)]
+      end
+
+      distinct = non_empty.uniq
+      if non_empty.length >= 3 && distinct.length < non_empty.length && distinct.length <= ENUM_MAX_DISTINCT
+        return [:string, "values: #{distinct.inspect} — enum?"]
+      end
+
+      [:string, nil]
+    end
+    private_class_method :string_inference
+
+    # @param value [Object]
+    # @return [Symbol] +:boolean+, +:integer+, +:float+, +:string+ or +:other+
+    def self.scalar_kind(value)
+      case value
+      when true, false then :boolean
+      when ::Integer then :integer
+      when ::Float then :float
+      when ::String then :string
+      else :other
+      end
+    end
+    private_class_method :scalar_kind
+
+    # +serialize+ refuses undeclared fields, so the mapping goes after them.
+    #
+    # @param name [String] the class name
+    # @param mappings [Hash{String=>Object}] attribute name → original sample key
+    # @param lines [Array<String>] the field lines
+    # @return [String] the class source
+    def self.build_class(name, mappings, lines)
+      body = lines.dup
+      body << '  # (no fields detected in samples)' if body.empty?
+      unless mappings.empty?
+        body << ''
+        body << "  serialize :json, #{mappings.map { |attr, key| "#{attr}: #{key.inspect}" }.join(", ")}"
+      end
+      "class #{name} < FieldStruct::Base\n#{body.join("\n")}\nend"
+    end
+    private_class_method :build_class
+
+    # @param declaration [String] the DSL call, without indentation
+    # @param comment_parts [String, nil] trailing-comment fragments; nil and
+    #   empty ones are dropped
+    # @return [String] the indented line, with a +#+ comment when any part remains
+    def self.decorate(declaration, *comment_parts)
+      parts = comment_parts.compact.reject(&:empty?)
+      line = "  #{declaration}"
+      parts.empty? ? line : "#{line} # #{parts.join("; ")}"
+    end
+    private_class_method :decorate
+
+    # @param present [Integer] samples holding the key
+    # @param total [Integer] the sample count
+    # @param missing [Integer] nil or blank values among them
+    # @return [String, nil]
+    def self.availability_comment(present, total, missing)
+      return "present #{present}/#{total}" if present < total
+      # Only note partial emptiness; when every sample is empty the scalar
+      # hint ("always empty — type unknown") already says so.
+      return "empty/null in #{missing}/#{total}" if missing.positive? && missing < total
+
+      nil
+    end
+    private_class_method :availability_comment
+
+    # First-seen union of keys across all samples.
+    #
+    # @param samples [Array<Hash{Object=>Object, nil}>]
+    # @return [Array<Object>]
+    def self.ordered_keys(samples)
+      samples.each_with_object([]) do |sample, keys|
+        sample.each_key { |key| keys << key unless keys.include?(key) }
+      end
+    end
+    private_class_method :ordered_keys
+
+    # @param base [String] the name wanted
+    # @param used [Array<String>] names taken so far (appended to)
+    # @return [String] +base+, or +base+ with a numeric suffix
+    def self.unique_name(base, used)
+      name = base
+      suffix = 1
+      while used.include?(name)
+        suffix += 1
+        name = "#{base}#{suffix}"
+      end
+      used << name
+      name
+    end
+    private_class_method :unique_name
+
+    # @param key [String] an attribute name
+    # @return [String] a constant-safe class name
+    def self.class_name_for(key)
+      name = camelize(key)
+      name = "N#{name}" unless name.match?(/\A[A-Z]/)
+      name
+    end
+    private_class_method :class_name_for
+
+    # @param str [String]
+    # @return [String]
+    def self.camelize(str)
+      str.to_s.split(/[^a-zA-Z0-9]+/).reject(&:empty?).map { |part| part[0].upcase + (part[1..] || '') }.join
+    end
+    private_class_method :camelize
+
+    # Naive: strip one trailing "s". Good enough for a prototype name; the
+    # developer renames as needed.
+    #
+    # @param str [String]
+    # @return [String]
+    def self.singularize(str)
+      str.end_with?('s') && str.length > 1 ? str[0..-2] : str
+    end
+    private_class_method :singularize
+
+    # @param key [Object] a sample key
+    # @return [String] a snake_case attribute name that +field+ accepts
+    def self.safe_attr(key)
+      attr = key.to_s.gsub(/([a-z\d])([A-Z])/, '\1_\2').gsub(/[^a-zA-Z0-9]+/, '_').downcase
+      attr = attr.sub(/\A_+/, '').sub(/_+\z/, '')
+      attr = "field_#{attr}" if attr.empty? || attr.match?(/\A\d/)
+      attr = "#{attr}_field" if RESERVED.include?(attr)
+      attr
+    end
+    private_class_method :safe_attr
+
+    # @param value [Object, nil]
+    # @return [Boolean]
+    def self.blank_string?(value)
+      value.is_a?(::String) && value.strip.empty?
+    end
+    private_class_method :blank_string?
+  end
+end

data/lib/field_struct/types/array.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module FieldStruct
+  module Types
+    # Array type. Coerces each element through the registered element
+    # type named by the +:of+ DSL option (resolved at field-declaration
+    # time and stashed as +options[:of_type]+ — a class, not a symbol).
+    #
+    # An optional +:element+ Hash carries the element type's own options
+    # (+strict:+, +base:+, +format:+, …), passed to every element's coerce:
+    #
+    #   optional :ids, :array, of: :integer, element: {strict: true, base: 16}
+    #
+    # A refused element is reported with its index — +element at index 2: …+ —
+    # and several with all of theirs (see {.elements_at}).
+    #
+    # Missing: +nil+ or empty array. ruby_type: +::Array+.
+    class Array < Base
+      # Native options: a required +of:+ naming the element type — a
+      # registered Symbol or a Class (a +Types::Base+ or +FieldStruct::Base+
+      # subclass) — and an +element:+ Hash of that element type's options.
+      #
+      # @return [::Hash{::Symbol => ::Hash{::Symbol => Object}}]
+      def self.own_option_schema
+        {
+          of: option(type: [::Symbol, ::Class], required: true),
+          element: option(type: [::Hash])
+        }
+      end
+
+      # The element type class behind an +of_type+ option, whether it holds
+      # a class (+:integer+ → {Types::Integer}) or a built instance (a
+      # {Types::Nested}). Its +option_schema+ is what +element:+ accepts.
+      #
+      # @param of_type [Class, Types::Base] an array field's +:of_type+ option
+      # @return [Class<Types::Base>] a {Types::Base} subclass
+      def self.element_class(of_type)
+        of_type.is_a?(::Class) ? of_type : of_type.class
+      end
+
+      # @param value [::Array<Object, nil>, nil] anything else raises TypeError
+      # @param of_type [Class, Types::Base, nil] the element type — a
+      #   Types::Base subclass for stock types, or an already-built
+      #   instance for parameterized types like {Types::Nested}. The DSL
+      #   stashes this when the user writes +of: :string+ / +of: SomeStruct+.
+      #   Required at the type level; nil here means the type was called
+      #   directly without DSL help.
+      # @param element [::Hash{::Symbol => Object, nil}, nil] the element
+      #   type's options, passed to every element's coerce (the DSL's
+      #   +element:+, already validated against the element type's schema)
+      # @return [::Array<Object, nil>, nil] each element coerced by +of_type+
+      # @raise [TypeError] when input is non-nil and not an Array
+      # @raise [ArgumentError] when +of_type+ is missing
+      # @raise [StandardError] whatever the element type raises on a bad
+      #   element; an ArgumentError, TypeError or RangeError keeps its class
+      #   and gains an +element at index N: + prefix — or, when several
+      #   elements are refused, +elements at index N, M (index N shown): +
+      def coerce(value, of_type: nil, element: nil, **)
+        return nil if value.nil?
+        raise ::TypeError, "expected Array, got #{value.class}" unless value.is_a?(::Array)
+        raise ArgumentError, 'array coerce requires of_type:' if of_type.nil?
+
+        element_type = element_type_for(of_type)
+        # A manual index and no empty **splat keep this hot loop as cheap as it
+        # was before element options (each_with_index.map + **{} cost ~40%).
+        index = -1
+        value.map do |item|
+          index += 1
+          element ? element_type.coerce(item, **element) : element_type.coerce(item)
+        rescue ArgumentError, ::TypeError, ::RangeError => e
+          # Off the hot loop: only a refused array pays for finding the rest.
+          raise_refused!(value, index, e, element_type, element)
+        end
+      end
+
+      # How many indexes an element error lists before counting the rest.
+      # @return [::Integer]
+      INDEXES_LISTED = 5
+
+      # Name a set of element indexes for an error message: one reads
+      # +element at index 2+, several +elements at index 2, 5+, and past
+      # {INDEXES_LISTED} the rest are counted (+… and 7 more+). Indexes only,
+      # never elements, so a message carries no value.
+      #
+      # @param indexes [::Array<::Integer>] ascending, at least one
+      # @return [::String]
+      def self.elements_at(indexes)
+        return "element at index #{indexes.first}" if indexes.size == 1
+
+        listed = indexes.first(INDEXES_LISTED).join(', ')
+        rest = indexes.size - INDEXES_LISTED
+        rest.positive? ? "elements at index #{listed} and #{rest} more" : "elements at index #{listed}"
+      end
+
+      # @param value [Object]
+      # @return [Boolean] +true+ when +nil+ or empty
+      def missing?(value)
+        return true if value.nil?
+        return true if value.respond_to?(:empty?) && value.empty?
+
+        false
+      end
+
+      # @return [Class] the top-level +::Array+ class
+      def ruby_type
+        ::Array
+      end
+
+      private
+
+      # Coerce the elements after the first refused one, so the error names
+      # every refused index, then raise the first element's error with them.
+      # The same message reaches every coercion_policy, :raise included —
+      # finishing the scan costs a refused array no more than an accepted one.
+      #
+      # @param value [::Array<Object, nil>] the input array
+      # @param first [::Integer] the index of the first refused element
+      # @param error [StandardError] what the element type raised for it
+      # @param element_type [Types::Base] the element type instance
+      # @param element [::Hash{::Symbol => Object, nil}, nil] element options
+      # @return [void]
+      # @raise [StandardError] +error+'s class, prefixed with the indexes
+      def raise_refused!(value, first, error, element_type, element)
+        indexes = [first]
+        (first + 1).upto(value.size - 1) do |index|
+          item = value[index]
+          element ? element_type.coerce(item, **element) : element_type.coerce(item)
+        rescue ArgumentError, ::TypeError, ::RangeError
+          indexes << index
+        end
+        shown = indexes.size == 1 ? '' : " (index #{first} shown)"
+        # Exception#exception keeps the class without calling a custom
+        # initializer; the indexes, never the elements, are added. The cause
+        # chain stays what it was, rather than gaining the unprefixed copy.
+        raise error.exception("#{self.class.elements_at(indexes)}#{shown}: #{error.message}"), cause: error.cause
+      end
+
+      # +of_type+ may be either a Types::Base subclass (the DSL form for
+      # stock types like +:string+) or an already-built Types::Base
+      # instance (the DSL form for parameterized types like
+      # {Types::Nested}). Both produce a single cached instance per
+      # configured element type.
+      #
+      # @param type_or_instance [Class<Types::Base>, Types::Base]
+      # @return [Types::Base]
+      def element_type_for(type_or_instance)
+        return type_or_instance unless type_or_instance.is_a?(::Class)
+
+        @element_type_instances ||= {}
+        @element_type_instances[type_or_instance] ||= type_or_instance.new
+      end
+    end
+  end
+end

data/lib/field_struct/types/base.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module FieldStruct
+  # Namespace for the built-in coercion types ({Types::String}, {Types::Integer},
+  # …) and the {Types::Base} contract that custom types implement.
+  module Types
+    # Abstract base for all FieldStruct type classes.
+    #
+    # Subclasses must implement {#coerce} and {#ruby_type}. They may override
+    # {#missing?} when their notion of "missing" is broader than nil-only
+    # (e.g. strings consider empty/whitespace missing, arrays consider empty
+    # missing).
+    class Base
+      # Native per-field options this type understands, as a frozen Hash of
+      # option-name (Symbol) → descriptor. Each descriptor is built by
+      # {.option} and carries the accepted value classes, whether the option
+      # is required at declaration time, and any Symbol presets it accepts.
+      #
+      # This merges {.own_option_schema} down the class chain so a subtype
+      # inherits its parent's options for free (e.g. {Types::UUID} picks up
+      # {Types::String}'s +format:+ / +enum:+). The merged result is frozen and
+      # memoized per type class — a type's option vocabulary is fixed at load,
+      # so this is computed once rather than on every field declaration.
+      #
+      # This is the single source of truth for both *validation* (the DSL
+      # checks declared values against these descriptors) and *discoverability*
+      # (an agent or human can ask a type what it accepts without reading
+      # source). Options *not* listed here are treated as foreign and pass
+      # through onto the Field untouched, available to downstream tooling.
+      #
+      # @return [::Hash{::Symbol => ::Hash{::Symbol => Object}}]
+      def self.option_schema
+        @option_schema ||= begin
+          inherited = superclass.respond_to?(:option_schema) ? superclass.option_schema : {}
+          inherited.merge(own_option_schema).freeze
+        end
+      end
+
+      # The options this type adds on top of its superclass's. Subclasses
+      # override *this* (not {.option_schema}) to declare their native options;
+      # the empty default means "adds nothing." {.option_schema} handles the
+      # inheritance merge.
+      #
+      # @return [::Hash{::Symbol => ::Hash{::Symbol => Object}}]
+      def self.own_option_schema
+        {}
+      end
+
+      # Build a normalized descriptor for {.option_schema}.
+      #
+      # @param type [::Class, ::Array<::Class>] the Ruby class(es) a declared
+      #   value may be an instance of
+      # @param required [Boolean] whether the option must be present at
+      #   field-declaration time
+      # @param presets [::Array<::Symbol>] Symbol preset names the option also accepts
+      # @return [::Hash{::Symbol => Object}] a frozen descriptor: +{ type:, required:, presets: }+
+      def self.option(type:, required: false, presets: [])
+        {type: ::Kernel.Array(type).freeze, required: required, presets: presets.to_a.freeze}.freeze
+      end
+
+      # Resolve symbolic preset references on the per-field options hash
+      # at field-declaration time. Default implementation passes options
+      # through unchanged; concrete types override to interpret their
+      # own options (e.g. +format: :iso8601+ → strftime string).
+      #
+      # @param options [::Hash{::Symbol => Object, nil}] the per-field options hash, as written by the user
+      # @return [::Hash{::Symbol => Object, nil}] possibly-modified options to store on the Field
+      def self.resolve_options(options)
+        options
+      end
+
+      # Resolve a declared +format:+ into the form coercion and rendering use.
+      #
+      # Declared options are kept exactly as the user wrote them — see
+      # {TimeFormatResolver} for why — so a Symbol preset name has to be
+      # expanded somewhere, and the type owning the preset table is the only
+      # thing that can do it. This default serves types with no preset table:
+      # a String passes through, a Symbol is refused.
+      #
+      # @param format [::String, ::Symbol, nil] the format as declared
+      # @return [::String, nil]
+      # @raise [ArgumentError] when given a Symbol and the type has no presets
+      def self.resolve_format(format)
+        return format if format.nil? || format.is_a?(::String)
+
+        raise ArgumentError, "#{name || "this type"} has no format presets; got #{format.inspect}"
+      end
+
+      # Coerce an input value into the type's domain.
+      #
+      # The contract here is intentionally loose — subclasses override with
+      # explicit kwargs for the options they consume (e.g. +format:+ for
+      # Date, +round:+ for Float, +of_type:+ for Array), plus a trailing
+      # +**+ catch-all so a call site that splats +field.options+ can pass
+      # keys that some types ignore. See each subclass's +coerce+ for the
+      # exact accepted options.
+      #
+      # @param value [Object] raw input — each subclass narrows this to
+      #   the inputs it actually accepts
+      # @return [Object] the coerced value
+      # @raise [NotImplementedError] always, unless overridden by a subclass
+      def coerce(value, **)
+        raise NotImplementedError, "#{self.class} must implement #coerce"
+      end
+
+      # Whether the given value should be treated as "missing" for the purpose
+      # of presence checks. The default is nil-only; subclasses override for
+      # emptier notions.
+      #
+      # @param value [Object]
+      # @return [Boolean]
+      def missing?(value)
+        value.nil?
+      end
+
+      # The native Ruby class a coerced value will be an instance of.
+      # Used by the (deferred) RBS generator and for introspection.
+      #
+      # @return [Class]
+      # @raise [NotImplementedError] always, unless overridden by a subclass
+      def ruby_type
+        raise NotImplementedError, "#{self.class} must implement #ruby_type"
+      end
+
+      # The RBS type expression {FieldStruct::RBS} emits for fields of this
+      # type, or +nil+ (the default) to derive one from {#ruby_type}. Override
+      # in a custom type whose values {#ruby_type} can't describe on its own —
+      # typically a generic class, which RBS needs type arguments for:
+      #
+      #   def ruby_type = ::Hash
+      #   def rbs_type  = '::Hash[::Symbol, ::String]'
+      #
+      # Without it a bare generic +ruby_type+ is emitted with +untyped+
+      # arguments (+::Hash[untyped, untyped]+). A field's own +rbs_type:+
+      # option wins over this. Fully qualify constants (+::Hash+, not
+      # +Hash+): the RBS is emitted inside the struct's module nesting.
+      #
+      # @return [::String, nil]
+      def rbs_type
+        nil
+      end
+
+      # Concise type-instance representation. The default shows just the
+      # type-class name (e.g. +#<FieldStruct::Types::String>+). Subclasses
+      # that carry parameter state (Nested, Union, …) override to surface
+      # what they wrap.
+      #
+      # @return [::String]
+      def inspect
+        full = self.class.name || 'AnonymousType'
+        prefixed = full.sub(/\AFieldStruct\b/, FieldStruct.inspect_namespace)
+        "#<#{prefixed}>"
+      end
+
+      # @param pp [Object] a PP-shaped sink (responds to +#text+)
+      # @return [void]
+      def pretty_print(pp)
+        pp.text(inspect)
+      end
+    end
+  end
+end