typemap 0.1.0

data/lib/typemap/mapper/rbs_types.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Typemap
+  class Mapper
+    # The type strategy for a project that keeps `sig/*.rbs` — written by hand, or by sord from
+    # YARD tags. A property's type is its reader's in the signature files: an `attr_reader` /
+    # `attr_accessor`, or a zero-argument `def name: () -> T`, found along the class's ancestors.
+    # `constrain type:` is still allowed for a property the signatures do not cover, but never
+    # for one they do — a type declared twice drifts (`D_types_declared`).
+    #
+    # Needs the `rbs` gem, the app's dependency and never Typemap's; only its parser is used,
+    # not its type environment (`R_rbs_parser`), and not a reader of our own (`D_rbs_gem_parser`).
+    class RBSTypes
+      # @param sig [Array<String>, nil] the `.rbs` files, or directories searched for them; `nil`
+      #   finds the `sig/` directory beside each class's own source, walking up from its file
+      # @raise [LoadError] if the `rbs` gem cannot be loaded
+      def initialize(sig: nil)
+        begin
+          require "rbs"
+        rescue ::LoadError => e
+          raise ::LoadError,
+                "Typemap::Mapper::RBSTypes needs the rbs gem: add `gem \"rbs\"` to the Gemfile (#{e.message})"
+        end
+        @sig = sig&.then { |paths| expand(paths) }
+        @indexes = {}
+        @lock = Mutex.new
+      end
+
+      # @param klass [Class] the class being read
+      # @param name [Symbol] the property
+      # @param constraint [Constrain::Constraint, nil] what `constrain` recorded for it
+      # @return [Object] the property's {Type}
+      # @raise [DefinitionError] when neither the signatures nor `constrain` give a type, when
+      #   both do, or the type is unsupported
+      def type_for(klass, name, constraint)
+        found = signature_type(klass, name)
+        if found && constraint&.type
+          raise DefinitionError, "type declared twice: in #{found[:where]} and by `constrain type:`; keep one"
+        end
+        return TypeBuilder.build(parse_type(constraint.type), constraint.type_owner.name) if constraint&.type
+
+        unless found
+          raise DefinitionError, "no type: #{klass}##{name} has no reader in #{files_for(klass).join(", ")}, " \
+                                 "and no `constrain :#{name}, type: \"…\"`"
+        end
+
+        build(found, name)
+      end
+
+      # A `constrain type:` string through the `rbs` gem's own parser, as a {TypeParser} tree.
+      #
+      # @param source [String]
+      # @return [Array]
+      # @raise [DefinitionError] on a syntax error or an unsupported type
+      def parse_type(source)
+        parsed = ::RBS::Parser.parse_type(source)
+        raise DefinitionError, "type #{source.inspect}: empty" unless parsed
+
+        tree(parsed)
+      rescue ::RBS::ParsingError => e
+        raise DefinitionError, "type #{source.inspect}: #{e.message}"
+      end
+
+      private
+
+      def build(found, name)
+        TypeBuilder.build(tree(found[:type]), found[:namespace])
+      rescue DefinitionError => e
+        raise DefinitionError, "#{e.message} (#{name} at #{found[:where]})"
+      end
+
+      # @return [Hash, nil] `{type:, namespace:, where:}` of the first ancestor whose signature
+      #   declares a reader for `name`
+      def signature_type(klass, name)
+        index = index_for(files_for(klass))
+        klass.ancestors.each do |mod|
+          next if mod.name.nil?
+
+          hits = (index[mod.name] || []).flat_map { |decl| readers(decl, name) }
+          next if hits.empty?
+
+          if hits.map { |hit| hit[:type].to_s }.uniq.size > 1
+            raise DefinitionError, "type declared twice: #{hits.map { |hit| hit[:where] }.join(" and ")}"
+          end
+
+          return hits.first.merge(namespace: mod.name)
+        end
+        nil
+      end
+
+      def readers(decl, name)
+        decl.members.filter_map do |member|
+          type = reader_type(member, name)
+          next unless type
+
+          location = member.location
+          { type: type, where: "#{location&.buffer&.name}:#{location&.start_line}" }
+        end
+      end
+
+      def reader_type(member, name)
+        case member
+        when ::RBS::AST::Members::AttrReader, ::RBS::AST::Members::AttrAccessor
+          member.type if member.name == name && member.kind == :instance
+        when ::RBS::AST::Members::MethodDefinition
+          return unless member.name == name && member.kind == :instance
+
+          function = member.overloads.first.method_type.type
+          function.return_type if function.respond_to?(:required_positionals) && function.required_positionals.empty?
+        end
+      end
+
+      # The `rbs` gem's type AST, translated to {TypeParser}'s tree.
+      def tree(type)
+        case type
+        when ::RBS::Types::ClassInstance then [:name, type.name.to_s, type.args.map { |arg| tree(arg) }]
+        when ::RBS::Types::Optional then [:optional, tree(type.type)]
+        when ::RBS::Types::Union then [:union, type.types.map { |member| tree(member) }]
+        when ::RBS::Types::Literal then [:literal, type.literal]
+        when ::RBS::Types::Bases::Bool then [:bool]
+        when ::RBS::Types::Bases::Nil then [:nil]
+        when ::RBS::Types::Bases::Any then [:untyped]
+        else TypeBuilder.unsupported(type.to_s)
+        end
+      end
+
+      def files_for(klass)
+        return @sig if @sig
+
+        source = klass.name && Module.const_source_location(klass.name)&.first
+        unless source
+          raise DefinitionError,
+                "#{klass.inspect}: no source file to find sig/ from; pass RBSTypes.new(sig: [...])"
+        end
+
+        dir = File.dirname(File.expand_path(source))
+        until File.directory?(File.join(dir, "sig"))
+          parent = File.dirname(dir)
+          raise DefinitionError, "#{klass}: no sig/ directory above #{source}" if parent == dir
+
+          dir = parent
+        end
+        expand([File.join(dir, "sig")])
+      end
+
+      def expand(paths)
+        paths.flat_map { |path| File.directory?(path) ? Dir.glob(File.join(path, "**", "*.rbs")) : [path] }.sort
+      end
+
+      def index_for(files)
+        @lock.synchronize { @indexes[files] ||= files.each_with_object({}) { |file, index| add_file(file, index) } }
+      end
+
+      def add_file(file, index)
+        buffer = ::RBS::Buffer.new(name: file, content: File.read(file))
+        _, _, decls = ::RBS::Parser.parse_signature(buffer)
+        add_decls(decls, [], index)
+      rescue ::RBS::ParsingError => e
+        raise DefinitionError, "#{file}: #{e.message}"
+      end
+
+      def add_decls(decls, namespace, index)
+        decls.each do |decl|
+          next unless decl.is_a?(::RBS::AST::Declarations::Class) || decl.is_a?(::RBS::AST::Declarations::Module)
+
+          written = decl.name.to_s
+          full = written.start_with?("::") ? written.delete_prefix("::").split("::") : namespace + written.split("::")
+          (index[full.join("::")] ||= []) << decl
+          add_decls(decl.members, full, index)
+        end
+      end
+    end
+  end
+end

data/lib/typemap/mapper/type.rb

@@ -0,0 +1,471 @@
+# frozen_string_literal: true
+
+module Typemap
+  class Mapper
+    # The types the mapper checks a value against — the small subset of RBS it supports, whether
+    # the type came from `constrain type:` or from `sig/*.rbs` (`D_types_declared`). Each type
+    # answers five questions:
+    #
+    # - `load(value, path, session, base)` — the value as the property holds it, or a
+    #   {DataError}; strict, never coerced, a whole number between Integer and Float aside;
+    # - `dump(value, mapper, path)` — the value as plain Hash/Array/scalar data;
+    # - `each_object(value, mapper, path) { |object, path| }` — the app's objects inside a value
+    #   that has passed `load` or `dump`, for the validation that walks the result;
+    # - `accepts?(value)` — whether a default fits;
+    # - `limits` — which of `constrain`'s `in:` / `format:` / `not_blank:` / `not_empty:` /
+    #   `unique:` the type can take.
+    #
+    # `to_s` is the RBS spelling, used in every message; `to_s(short: true)` drops each class's
+    # namespace, for load messages, whose reader writes the file and never sees the code.
+    #
+    # @api private
+    module Type
+      # `expected Integer, got "70"; remove the quotes`.
+      #
+      # @param type [#to_s] the expected type
+      # @param value [Object] what was found instead
+      # @param path [String]
+      # @param wording [Module] spells the found value: the load's {Wording}, {Wording::Ruby} on dump
+      # @param found [String, nil] words for the found value, in place of the wording's
+      # @param hint [String, nil] the fix, for a mistake whose fix is mechanical
+      # @raise [DataError] always
+      def self.mismatch(type, value, path, wording: Wording::Ruby, found: nil, hint: nil)
+        detail = "expected #{type}, got #{found || wording.found(value)}"
+        raise DataError.new(path, hint ? "#{detail}; #{hint}" : detail)
+      end
+
+      # @param klass [Class]
+      # @return [String] `Server` for `Shared::Config::Server`
+      def self.short_name(klass)
+        klass.name&.split("::")&.last || klass.inspect
+      end
+
+      # Whether the block loads without an error, for a hint on a value that has already failed;
+      # the loaded value is dropped.
+      #
+      # @yieldreturn [Object] the value loaded
+      # @return [Boolean]
+      def self.loads?
+        yield
+        true
+      rescue Error
+        false
+      end
+
+      # Whether a file wrote the value unquoted where a String belongs — a number, a bool, a
+      # parser's date-time: YAML's `no` is `false`, `1.10` is the Float `1.1`.
+      #
+      # @param value [Object]
+      # @return [Boolean]
+      def self.unquoted?(value)
+        !value.nil? && [String, Symbol, Array, Hash].none? { |klass| value.is_a?(klass) }
+      end
+
+      # A String a number's quotes were put around, `"70"`. Not what `Integer()` takes: `"0x1A"`
+      # and `"1_000"` may not have been meant as numbers.
+      NUMBER_TEXT = { Integer => /\A[+-]?\d+\z/, Float => /\A[+-]?\d+(\.\d+)?([eE][+-]?\d+)?\z/ }.freeze
+
+      # @param path [String]
+      # @param key [String, Symbol]
+      # @return [String] the path of `key` under `path`
+      def self.child(path, key)
+        path.empty? ? key.to_s : "#{path}.#{key}"
+      end
+
+      # `Integer`, `Float` or `String`: the value must be an instance. On load alone a whole number
+      # crosses between the two numeric classes, exactly or not at all — `5` loads as `5.0`, `5.0`
+      # as `5`, `5.1` raises (`D_whole_numbers`); a default and a dumped value stay strict.
+      #
+      # @!attribute [r] klass
+      #   @return [Class] `Integer`, `Float` or `String`
+      Scalar = Data.define(:klass) do
+        def load(value, path, session, _base)
+          return value if value.is_a?(klass)
+
+          whole = Type.whole_number(value, klass)
+          return whole unless whole.nil?
+
+          wording = session.wording
+          hint = if klass == String
+                   wording.quote(value) if Type.unquoted?(value)
+                 elsif value.is_a?(String) && Type::NUMBER_TEXT.fetch(klass).match?(value)
+                   wording.unquote
+                 end
+          Type.mismatch(self, value, path, wording: wording, hint: hint)
+        end
+
+        def dump(value, _mapper, path) = (value.is_a?(klass) ? value : Type.mismatch(self, value, path))
+        def each_object(_value, _mapper, _path) = nil
+        def accepts?(value) = value.is_a?(klass)
+        def limits = klass == String ? %i[in format not_blank] : %i[in]
+        def numeric? = klass != String
+        def nested_classes = []
+        def to_s(**) = klass.name
+      end
+
+      # `bool`: `true` or `false`.
+      Bool = Data.define do
+        def load(value, path, session, _base)
+          return value if accepts?(value)
+
+          wording = session.wording
+          Type.mismatch(self, value, path, wording: wording, hint: (wording.unquote if %w[true false].include?(value)))
+        end
+
+        def dump(value, _mapper, path) = (accepts?(value) ? value : Type.mismatch(self, value, path))
+        def each_object(_value, _mapper, _path) = nil
+        def accepts?(value) = [true, false].include?(value)
+        def limits = []
+        def numeric? = false
+        def nested_classes = []
+        def to_s(**) = "bool"
+      end
+
+      # A union of literals, `"short" | "verbose"`: the value must equal one of them, class
+      # included — `1.0` is not `1`.
+      #
+      # @!attribute [r] values
+      #   @return [Array<String, Integer, Float, Boolean>]
+      Literals = Data.define(:values) do
+        def load(value, path, session, _base)
+          return value if accepts?(value)
+
+          wording = session.wording
+          hint = (wording.quote(value) if values.all?(String) && Type.unquoted?(value))
+          Type.mismatch(self, value, path, wording: wording, hint: hint)
+        end
+
+        def dump(value, _mapper, path) = (accepts?(value) ? value : Type.mismatch(self, value, path))
+        def each_object(_value, _mapper, _path) = nil
+        def accepts?(value) = values.any? { |literal| literal.eql?(value) }
+        def limits = []
+        def numeric? = false
+        def nested_classes = []
+        def to_s(**) = values.map(&:inspect).join(" | ")
+      end
+
+      # `T?`: `nil`, or a `T`.
+      #
+      # @!attribute [r] inner
+      #   @return [Object] the type of a non-nil value
+      Optional = Data.define(:inner) do
+        def load(value, path, session, base) = (value.nil? ? nil : inner.load(value, path, session, base))
+        def dump(value, mapper, path) = (value.nil? ? nil : inner.dump(value, mapper, path))
+        def each_object(value, mapper, path, &) = (inner.each_object(value, mapper, path, &) unless value.nil?)
+        def accepts?(value) = value.nil? || inner.accepts?(value)
+        def limits = inner.limits
+        def numeric? = inner.numeric?
+        def nested_classes = inner.nested_classes
+
+        def to_s(short: false)
+          inner.is_a?(Literals) && inner.values.size > 1 ? "(#{inner})?" : "#{inner.to_s(short: short)}?"
+        end
+      end
+
+      # `Array[T]`: an Array whose every element is a `T`; an element's path is `key[3]`. A lone `T`
+      # where the Array belongs — TOML's `[server]` for `[[server]]` — raises
+      # `server: expected Array[Server], got a single Server; wrap it in an array`, the fix in the
+      # load's {Wording}.
+      #
+      # An entry whose class has a class method `entry_name(raw)` is named in its errors after its
+      # index — `server[1] "grok".url: required` — `raw` being the entry as a file would hold it:
+      #
+      #   def self.entry_name(raw) = raw["id"]
+      #
+      # == Implementation details
+      #
+      # The name is worked out only when an entry's error passes through, so a load that succeeds
+      # never calls `entry_name`. `raw` is always plain data with String keys: on load the file's
+      # Hash, on validation and dump the entry dumped by {Mapper#entry_hash}. The name is the
+      # result's `to_s.strip`; no name, just the index, when that is empty — `nil` or `"  "`. When
+      # `entry_name` raises, a warning says why, and the error the user needs is raised unnamed.
+      #
+      # @!attribute [r] element
+      #   @return [Object] the elements' type
+      ArrayOf = Data.define(:element) do
+        def load(value, path, session, _base)
+          single(value, path, session) unless value.is_a?(Array)
+          value.each_with_index.map do |item, i|
+            at = "#{path}[#{i}]"
+            named(item, at, session.mapper) { element.load(item, at, session, nil) }
+          end
+        end
+
+        def dump(value, mapper, path)
+          Type.mismatch(self, value, path) unless value.is_a?(Array)
+          value.each_with_index.map do |item, i|
+            at = "#{path}[#{i}]"
+            named(item, at, mapper) { element.dump(item, mapper, at) }
+          end
+        end
+
+        def each_object(value, mapper, path, &)
+          value.each_with_index do |item, i|
+            at = "#{path}[#{i}]"
+            named(item, at, mapper) { element.each_object(item, mapper, at, &) }
+          end
+        end
+
+        def accepts?(value) = value.is_a?(Array) && value.all? { |item| element.accepts?(item) }
+        def limits = %i[not_empty unique]
+        def numeric? = false
+        def nested_classes = element.nested_classes
+        def to_s(short: false) = "Array[#{element.to_s(short: short)}]"
+
+        # Raises on the second of two entries whose keys are `eql?` — `nil` and `nil` included,
+        # as Ruby compares them. The path ends in the property when `by` names one; the detail
+        # names the first entry by index, then the shared key when it is plain data.
+        #
+        # @param value [Array] entries that have passed their own validation
+        # @param by [true, Symbol, Proc] the entry itself, its property, or a function of it
+        # @param path [String]
+        # @param mapper [Mapper, nil] names the entry; `nil` leaves the bare index
+        # @return [void]
+        # @raise [DataError] on a duplicate
+        def check_unique(value, by, path, mapper)
+          seen = {}
+          value.each_with_index do |item, i|
+            key = Type.unique_key(item, by)
+            first = seen[key]
+            seen[key] = i if first.nil?
+            next if first.nil?
+
+            at = "#{path}[#{i}]"
+            detail = "duplicate of #{path}[#{first}]#{", both #{key.inspect}" if Type.plain?(key)}"
+            error = DataError.new(by.is_a?(Symbol) ? "#{at}.#{by}" : at, detail)
+            mapper ? named(item, at, mapper) { raise error } : raise(error)
+          end
+        end
+
+        private
+
+        # @raise [DataError] always
+        def single(value, path, session)
+          spelled = to_s(short: true)
+          wording = session.wording
+          if single_entry?(value, path, session)
+            Type.mismatch(spelled, value, path, found: "a single #{entry_type.to_s(short: true)}",
+                                                hint: wording.wrap(path, value.is_a?(Hash)))
+          end
+          Type.mismatch(spelled, value, path, wording: wording)
+        end
+
+        # @return [Boolean] whether `value` is one entry: {Plan#entry_like?} for a class, one that
+        #   loads otherwise — there being no keys to compare
+        def single_entry?(value, path, session)
+          return false if value.nil?
+
+          klass = entry_class
+          return session.mapper.plan_for(klass).entry_like?(value) if klass
+
+          Type.loads? { element.load(value, path, session, nil) }
+        end
+
+        # @return [Object] the type of a non-nil entry, `Server` for `Array[Server?]`
+        def entry_type = element.is_a?(Optional) ? element.inner : element
+
+        # @return [Class, nil] the entries' class, `Server` for `Array[Server?]` too
+        def entry_class = (entry_type.klass if entry_type.is_a?(ClassRef))
+
+        # @return [Object] the block's result
+        # @raise [DataError] the block's, its path naming the entry when it has a name
+        def named(item, at, mapper)
+          yield
+        rescue DataError => e
+          name = entry_name(item, at, mapper)
+          raise e if name.nil?
+
+          renamed = DataError.new("#{at} #{name.inspect}#{e.path.delete_prefix(at)}", e.detail)
+          renamed.set_backtrace(e.backtrace)
+          raise renamed, cause: e.cause
+        end
+
+        # @return [String, nil]
+        def entry_name(item, at, mapper)
+          klass = entry_class
+          return unless klass.respond_to?(:entry_name)
+
+          raw = case item
+                when Hash then item.transform_keys(&:to_s)
+                when klass then mapper.entry_hash(item)
+                end
+          name = raw && klass.entry_name(raw).to_s.strip
+          name unless name.nil? || name.empty?
+        rescue StandardError => e
+          warn "Typemap: #{at} left unnamed, #{klass}.entry_name: #{e.class}: #{e.message}"
+          nil
+        end
+      end
+
+      # `Hash[String, T]`: a Hash with String keys (a Symbol key is taken as its String) and a
+      # `T` under each.
+      #
+      # @!attribute [r] value
+      #   @return [Object] the values' type
+      HashOf = Data.define(:value) do
+        def load(raw, path, session, _base)
+          Type.mismatch(to_s(short: true), raw, path, wording: session.wording) unless raw.is_a?(Hash)
+          Type.string_keys(raw, path).to_h { |key, item| [key, value.load(item, Type.child(path, key), session, nil)] }
+        end
+
+        def dump(raw, mapper, path)
+          Type.mismatch(self, raw, path) unless raw.is_a?(Hash)
+          Type.string_keys(raw, path).to_h { |key, item| [key, value.dump(item, mapper, Type.child(path, key))] }
+        end
+
+        def each_object(raw, mapper, path, &)
+          raw.each { |key, item| value.each_object(item, mapper, Type.child(path, key), &) }
+        end
+
+        def accepts?(raw) = raw.is_a?(Hash) && raw.all? { |key, item| key.is_a?(String) && value.accepts?(item) }
+        def limits = %i[not_empty]
+        def numeric? = false
+        def nested_classes = value.nested_classes
+        def to_s(short: false) = "Hash[String, #{value.to_s(short: short)}]"
+      end
+
+      # `Object`: plain data passed through as the file holds it, for a value whose meaning is
+      # someone else's — `Hash[String, Object]` for extra keys sent to a server verbatim:
+      #
+      #   { "kwargs" => { "enable_thinking" => false, stop: nil } }    # in
+      #   { "kwargs" => { "enable_thinking" => false, "stop" => nil } } # out, new containers
+      #
+      # Plain data is what Typemap's other types load — a String, Integer, Float, bool, Array or
+      # Hash, `nil` nested inside — on load and dump alike, so a `Proc` or a TOML date-time
+      # raises. Keys are Strings all the way down, a Symbol taken as its String. `nil` in its own
+      # place needs `Object?`, as every type does. See `D_object_plain_data`.
+      Plain = Data.define do
+        def load(value, path, session, _base) = copy(value, path, session.wording)
+        def dump(value, _mapper, path) = copy(value, path, Wording::Ruby)
+
+        def each_object(_value, _mapper, _path) = nil
+        def accepts?(value) = !value.nil? && Type.plain?(value)
+        def limits = []
+        def numeric? = false
+        def nested_classes = []
+        def to_s(**) = "Object"
+
+        private
+
+        def copy(value, path, wording)
+          Type.mismatch(self, value, path, wording: wording) if value.nil?
+          Type.plain(value, path, wording)
+        end
+      end
+
+      # A class of the app's own — a data class or an accessor class — loaded from a Hash by
+      # the mapper, recursively.
+      #
+      # @!attribute [r] klass
+      #   @return [Class]
+      ClassRef = Data.define(:klass) do
+        def load(value, path, session, base) = session.load_object(klass, value, path, base)
+
+        def dump(value, mapper, path)
+          Type.mismatch(self, value, path) unless value.is_a?(klass)
+          mapper.dump_object(value, path)
+        end
+
+        def each_object(value, _mapper, path) = yield(value, path)
+
+        def accepts?(value) = value.is_a?(klass)
+        def limits = []
+        def numeric? = false
+        def nested_classes = [klass]
+        def to_s(short: false) = short ? Type.short_name(klass) : (klass.name || klass.inspect)
+      end
+
+      # A whole number as the other numeric class, when it converts exactly: `5` as a Float is
+      # `5.0`, `5.0` as an Integer is `5`. Not `5.1`, NaN or infinity as an Integer, nor
+      # `2**53 + 1` as a Float, which would round.
+      #
+      # @param value [Object]
+      # @param klass [Class] the class the property declares
+      # @return [Integer, Float, nil] the converted value, or nil when it does not convert exactly
+      def self.whole_number(value, klass)
+        if klass == Float && value.is_a?(Integer)
+          float = value.to_f
+          float if float.finite? && float.to_i == value
+        elsif klass == Integer && value.is_a?(Float)
+          value.to_i if value.finite? && value.to_i == value
+        end
+      end
+
+      # @param item [Object] an array entry
+      # @param by [true, Symbol, Proc] `unique: true`, or `unique_by:`
+      # @return [Object] what `item` is compared by
+      def self.unique_key(item, by)
+        case by
+        when true then item
+        when Symbol then item.public_send(by)
+        else by.call(item)
+        end
+      end
+
+      PLAIN_SCALARS = [String, Integer, Float, TrueClass, FalseClass, NilClass].freeze
+
+      # A copy of plain data, every Hash's keys as Strings.
+      #
+      # @param value [Object]
+      # @param path [String]
+      # @param wording [Module] the {Wording} that spells a value no type loads
+      # @return [Object] the copy
+      # @raise [DataError] on a value no Typemap type loads, or a key neither String nor Symbol
+      def self.plain(value, path, wording)
+        case value
+        when Array then value.each_with_index.map { |item, i| plain(item, "#{path}[#{i}]", wording) }
+        when Hash then string_keys(value, path).to_h { |key, item| [key, plain(item, child(path, key), wording)] }
+        when *PLAIN_SCALARS then value
+        else mismatch("plain data (String, Integer, Float, bool, nil, Array or Hash)", value, path, wording: wording)
+        end
+      end
+
+      # Freezes `value` in place when it is an Array, a Hash or a String, then each item, key and
+      # value inside; anything else is left as is, a data instance being frozen already and an
+      # accessor instance mutable by design. Freezes a String the caller passed in, too
+      # (`D_frozen_containers`).
+      #
+      # @param value [Object]
+      # @return [void]
+      def self.deep_freeze(value)
+        case value
+        when Array then value.freeze.each { |item| deep_freeze(item) }
+        when Hash
+          value.freeze.each do |key, item|
+            deep_freeze(key)
+            deep_freeze(item)
+          end
+        when String then value.freeze
+        end
+        nil
+      end
+
+      # @param value [Object]
+      # @return [Boolean] whether `value` is plain data with String keys, as a default must be
+      def self.plain?(value)
+        case value
+        when Array then value.all? { |item| plain?(item) }
+        when Hash then value.all? { |key, item| key.is_a?(String) && plain?(item) }
+        else PLAIN_SCALARS.any? { |klass| value.is_a?(klass) }
+        end
+      end
+
+      # A Hash's keys as Strings, a Symbol key taken as its String.
+      #
+      # @param hash [Hash]
+      # @param path [String]
+      # @return [Hash{String => Object}]
+      # @raise [DataError] on a key that is neither, or on `"a"` and `:a` both present
+      def self.string_keys(hash, path)
+        hash.each_with_object({}) do |(key, item), out|
+          raise DataError.new(path, "key #{key.inspect} is not a String") unless key.is_a?(String) || key.is_a?(Symbol)
+
+          name = key.to_s
+          raise DataError.new(path, "key #{name} given twice, as a String and as a Symbol") if out.key?(name)
+
+          out[name] = item
+        end
+      end
+    end
+  end
+end