typemap 0.1.0

data/lib/typemap/error.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Typemap
+  # The root of Typemap's own errors; rescue it to catch both kinds below.
+  class Error < StandardError
+  end
+
+  # The data does not fit the class: a value of the wrong type or outside its limits, an unknown
+  # key, a required key missing, a failed `validate`. The file's author fixes it; the message starts
+  # with the path of the offending value and, for a classic mistake whose fix is mechanical, ends
+  # with the fix, worded for the `source:` given to `load`:
+  #
+  #   ballooning.raise_at_percent: expected Integer, got "70"; remove the quotes        # :toml
+  #   server: expected Array[Server], got a single Server; write [[server]], not [server], or server = [{…}]
+  #   ui.sandbox: unknown key; sandbox belongs to the top level, before any [header]
+  #   ballooning.raise_at_percent: expected Integer, got String "70"                    # :ruby
+  #
+  # An array entry whose class names it with `entry_name` shows that after its index,
+  # `server[1] "grok".url`.
+  #
+  # A type is named as RBS spells it, a class without its namespace on load (`Server`, not
+  # `Shared::Config::Server`), in full on dump, never by a format's word for a Hash, TOML's "table"
+  # (`D_source_wording`). No line number: the parsers keep none in the Hash they return, so the
+  # path stands in.
+  class DataError < Error
+    # @return [String] the dotted path of the offending value, `""` for the root object
+    attr_reader :path
+
+    # @return [String] what is wrong with the value: the message without its path
+    attr_reader :detail
+
+    # @param path [String] the dotted path of the offending value, `""` for the root
+    # @param detail [String] what is wrong with it
+    def initialize(path, detail)
+      @path = path
+      @detail = detail
+      super(path.empty? ? detail : "#{path}: #{detail}")
+    end
+  end
+
+  # The class cannot be mapped: a property with no type, a type declared twice, a default the
+  # type rejects, a class `new` cannot build bare. The class's author fixes it; it is raised
+  # when the mapper first reads the class, whatever the file holds.
+  class DefinitionError < Error
+  end
+end

data/lib/typemap/mapper/accessor_shape.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Typemap
+  class Mapper
+    # The shape of an accessor class — a mutable class built by a bare `new` and then its
+    # setters. Its properties are its public reader + writer pairs (`D_accessor_properties`):
+    # only methods count, never ivars, and a private or protected accessor is left out.
+    #
+    # @api private
+    module AccessorShape
+      READER = /\A[a-z_][A-Za-z0-9_]*\z/
+      private_constant :READER
+
+      # Public reader + writer pairs in declaration order: sorted by the reader's source line,
+      # since `public_instance_methods` comes in no declared order (`R_ruby_reflection`), and
+      # within one line — `attr_accessor :a, :b` — by where the name stands in it, read from the
+      # source file. A reader with no source location (one defined in C) sorts last, by name.
+      #
+      # @param klass [Class]
+      # @return [Array<Symbol>]
+      def self.properties(klass)
+        names = klass.public_instance_methods.select do |name|
+          name.match?(READER) && klass.public_method_defined?(:"#{name}=") && klass.instance_method(name).arity.zero?
+        end
+        sources = Hash.new { |cache, file| cache[file] = File.exist?(file) ? File.readlines(file) : [] }
+        names.sort_by do |name|
+          file, line = klass.instance_method(name).source_location
+          next [1, "", 0, 0, name.to_s] unless file
+
+          column = sources[file][line - 1]&.index(/\b#{name}\b/) || 0
+          [0, file, line, column, name.to_s]
+        end
+      end
+
+      # A bare `new` sets every property, so none is required by the class itself; `required:`
+      # says it instead.
+      #
+      # @param _klass [Class]
+      # @param _names [Array<Symbol>]
+      # @return [Array<Symbol>] always empty
+      def self.required_keywords(_klass, _names) = []
+
+      # @param _klass [Class]
+      # @param _names [Array<Symbol>] the properties `constrain` gave `required:`
+      # @return [void]
+      def self.check_required_option(_klass, _names) = nil
+
+      # @param object [Object]
+      # @param name [Symbol]
+      # @return [Object] the property's value
+      def self.read(object, name) = object.public_send(name)
+
+      # Leaves a property's value mutable, as the class is (`D_frozen_containers`).
+      #
+      # @param _value [Object]
+      # @return [void]
+      def self.freeze_value(_value) = nil
+
+      # A fresh bare `new`, then a setter for every property: `base`'s value, or the loaded one.
+      # `base` itself is never changed — it may be a default shared beyond this load.
+      #
+      # @param klass [Class]
+      # @param base [Object] supplies every value `loaded` does not
+      # @param loaded [Hash{Symbol => Object}] the values read from the file
+      # @param names [Array<Symbol>] the mapped properties
+      # @return [Object]
+      def self.build(klass, base, loaded, names)
+        object = klass.new
+        names.each { |name| object.public_send(:"#{name}=", loaded.fetch(name) { base.public_send(name) }) }
+        object
+      end
+    end
+  end
+end

data/lib/typemap/mapper/basic_types.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Typemap
+  class Mapper
+    # The default type strategy, needing no gem: every property's type comes from
+    # `constrain type:`, parsed by Typemap's own {TypeParser}. A property without one raises —
+    # a type is never read off the default (`D_types_declared`).
+    class BasicTypes
+      # @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 `constrain` gave no type, or the type is unsupported
+      def type_for(klass, name, constraint)
+        unless constraint&.type
+          raise DefinitionError, "no type: give it `constrain :#{name}, type: \"…\"` " \
+                                 "(#{klass} uses Typemap::Constrain), or map it with Typemap::Mapper::RBSTypes"
+        end
+
+        TypeBuilder.build(TypeParser.parse(constraint.type), constraint.type_owner.name)
+      end
+    end
+  end
+end

data/lib/typemap/mapper/data_shape.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Typemap
+  class Mapper
+    # The shape of a data class (`Data.define`): its properties are its `members`, in order, and
+    # an instance is built in one `new(**values)`. A keyword without a default is a required key:
+    #
+    #     Llm = Data.define(:api_key, :model) do
+    #       def initialize(api_key:, model: "gpt-5") = super   # api_key required, model not
+    #     end
+    #
+    # @api private
+    module DataShape
+      READABLE = %i[key keyreq].freeze
+      private_constant :READABLE
+
+      # @param klass [Class] a `Data` subclass
+      # @return [Array<Symbol>] its members, in declaration order
+      def self.properties(klass) = klass.members
+
+      # The keywords `klass.new` cannot build without, read off `initialize`: every member when
+      # `Data`'s own `initialize` is left as is, else its `name:` keywords.
+      #
+      # @param klass [Class] a `Data` subclass
+      # @param names [Array<Symbol>] the mapped members, `ignore`d ones left out
+      # @return [Array<Symbol>]
+      # @raise [DefinitionError] on an `initialize` taking anything but `name:` / `name: default`
+      #   keywords, one with no keyword for a member, or one requiring a keyword the file cannot give
+      def self.required_keywords(klass, names)
+        init = klass.instance_method(:initialize)
+        return unmapped_checked(klass, klass.members, names) if init.owner == Data
+
+        params = init.parameters
+        unless params.all? { |kind, _| READABLE.include?(kind) }
+          raise DefinitionError, "#{klass}#initialize takes #{params.inspect}; Typemap reads which keys are " \
+                                 "required only from `name:` and `name: default` keywords"
+        end
+        missing = klass.members - params.map(&:last)
+        raise DefinitionError, "#{klass}#initialize takes no keyword #{missing.join(", ")}" unless missing.empty?
+
+        unmapped_checked(klass, params.filter_map { |kind, name| name if kind == :keyreq }, names)
+      end
+
+      # @param klass [Class]
+      # @param names [Array<Symbol>] the properties `constrain` gave `required:`
+      # @return [void]
+      # @raise [DefinitionError] unless `names` is empty: a data class's keyword without a default
+      #   is how it says "required"
+      def self.check_required_option(klass, names)
+        return if names.empty?
+
+        raise DefinitionError, "#{klass}##{names.first}: required: is for an accessor class; " \
+                               "in a data class, a keyword without a default is required"
+      end
+
+      # @param object [Data]
+      # @param name [Symbol]
+      # @return [Object] the property's value
+      def self.read(object, name) = object.public_send(name)
+
+      # Freezes a property's value in place, Arrays, Hashes and Strings all the way down: the
+      # instance is frozen, so what it holds is too (`D_frozen_containers`).
+      #
+      # @param value [Object]
+      # @return [void]
+      def self.freeze_value(value) = Type.deep_freeze(value)
+
+      # @param klass [Class]
+      # @param base [Data] supplies every value `loaded` does not
+      # @param loaded [Hash{Symbol => Object}] the values read from the file
+      # @return [Data]
+      def self.build(klass, base, loaded)
+        klass.new(**klass.members.to_h { |name| [name, base.public_send(name)] }, **loaded)
+      end
+
+      # @return [Array<Symbol>] `required`
+      # @raise [DefinitionError] if one of them is not mapped, so no file can give it
+      def self.unmapped_checked(klass, required, names)
+        unmapped = required - names
+        return required if unmapped.empty?
+
+        raise DefinitionError, "#{klass}#initialize requires #{unmapped.join(", ")}, not a mapped property, " \
+                               "so no file can give it"
+      end
+      private_class_method :unmapped_checked
+    end
+  end
+end

data/lib/typemap/mapper/limits.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Typemap
+  class Mapper
+    # `constrain`'s limits for one property, checked after its type. A `nil` value (of a `T?`
+    # type) is never limited.
+    #
+    # @!attribute [r] in
+    #   @return [Range, Array, nil] the allowed range of a number, or the allowed values
+    # @!attribute [r] format
+    #   @return [Regexp, nil] the pattern a String must match
+    # @!attribute [r] not_blank
+    #   @return [Boolean] a String must hold more than whitespace
+    # @!attribute [r] not_empty
+    #   @return [Boolean] an Array or a Hash must hold at least one element
+    # @!attribute [r] unique
+    #   @return [Boolean] no two entries of an Array may be equal
+    # @!attribute [r] unique_by
+    #   @return [Symbol, Proc, nil] what no two entries of an Array may share: a property, or a
+    #     function of the entry
+    #
+    # @api private
+    Limits = Data.define(:in, :format, :not_blank, :not_empty, :unique, :unique_by) do
+      # @return [Limits] no limits at all
+      def self.none = new(in: nil, format: nil, not_blank: false, not_empty: false, unique: false, unique_by: nil)
+
+      # Raises unless the type can take these limits: `in:` a Range on a number, `in:` an Array
+      # on a number or a String, `format:` and `not_blank:` on a String, `not_empty:` on an Array
+      # or a Hash, `unique:` and `unique_by:` on an Array — `unique:` on entries with value
+      # equality, `unique_by:` a Symbol on entries of a class that has that property.
+      #
+      # @param type [Object] the property's {Type}
+      # @return [void]
+      # @raise [DefinitionError]
+      def check_against(type)
+        check_in_against(type)
+        check_unique_against(type)
+        if format && !type.limits.include?(:format)
+          raise DefinitionError, "format: #{format.inspect} limits only a String, not #{type}"
+        end
+
+        if not_blank && !type.limits.include?(:not_blank)
+          hint = ("; an Array or a Hash takes not_empty:" if type.limits.include?(:not_empty))
+          raise DefinitionError, "not_blank: limits only a String, not #{type}#{hint}"
+        end
+        return unless not_empty && !type.limits.include?(:not_empty)
+
+        # A String takes not_empty: in Bean Validation; here it would pass "  ", the typo
+        # not_blank: exists to catch.
+        hint = ("; a String takes not_blank:, which refuses \"  \" too" if type.limits.include?(:not_blank))
+        raise DefinitionError, "not_empty: limits only an Array or a Hash, not #{type}#{hint}"
+      end
+
+      # Raises in words a person editing the file reads, not Ruby's `1..`:
+      #
+      #     must be 1 to 100, got 170                  # in: 1..100
+      #     must be at least 1 and below 10, got 10    # in: 1...10
+      #     must be one of "short", "verbose", got "x" # in: %w[short verbose]
+      #     must not be blank                          # not_blank: true, got "  "
+      #     must not be empty                          # not_empty: true, got []
+      #
+      # @param value [Object] a value that has already passed the type
+      # @param path [String]
+      # @return [void]
+      # @raise [DataError] if the value is outside the limits
+      def check(value, path)
+        return if value.nil?
+
+        raise DataError.new(path, "must not be blank") if not_blank && value.strip.empty?
+        raise DataError.new(path, "must not be empty") if not_empty && value.empty?
+
+        allowed = self.in
+        if allowed.is_a?(Range) && !allowed.cover?(value)
+          raise DataError.new(path, "must be #{Limits.range_words(allowed)}, got #{value.inspect}")
+        end
+        if allowed.is_a?(Array) && !allowed.include?(value)
+          raise DataError.new(path, "must be one of #{allowed.map(&:inspect).join(", ")}, got #{value.inspect}")
+        end
+        return unless format && !format.match?(value)
+
+        raise DataError.new(path, "#{value.inspect} does not match #{format.inspect}")
+      end
+
+      # Raises on the second of two entries sharing a key, under `unique:` or `unique_by:`:
+      #
+      #     server[2] "local".id: duplicate of server[0], both "local"   # unique_by: :id
+      #     mirror[3]: duplicate of mirror[1], both "http://x"           # unique_by: a Proc
+      #
+      # Kept apart from {#check}, which knows no type: the entries are named through the
+      # property's `Array[T]`.
+      #
+      # @param value [Array, nil] a value that has already passed the type
+      # @param type [Object] the property's {Type}, an `Array[T]` or an `Array[T]?`
+      # @param path [String]
+      # @param mapper [Mapper, nil] names the entries; `nil` for a default, checked before any
+      #   entry can be dumped for its name
+      # @return [void]
+      # @raise [DataError] on a duplicate
+      def check_unique(value, type, path, mapper)
+        by = unique_by || (true if unique)
+        return if by.nil? || value.nil?
+
+        Limits.array_of(type).check_unique(value, by, path, mapper)
+      end
+
+      # @param type [Object] an `Array[T]`, or an `Array[T]?`
+      # @return [Type::ArrayOf]
+      def self.array_of(type) = type.is_a?(Type::Optional) ? type.inner : type
+
+      # @param range [Range] a numeric range; an endless or beginless one too
+      # @return [String] `1 to 100`, `at least 1`, `at most 100`, `below 10`, `at least 1 and below 10`
+      def self.range_words(range)
+        from = range.begin&.inspect
+        to = range.end&.inspect
+        upper = range.exclude_end? ? "below #{to}" : "at most #{to}"
+        if from && to
+          range.exclude_end? ? "at least #{from} and #{upper}" : "#{from} to #{to}"
+        elsif from
+          "at least #{from}"
+        else
+          upper
+        end
+      end
+
+      private
+
+      def check_unique_against(type)
+        return unless unique || unique_by
+        if unique && unique_by
+          raise DefinitionError, "unique: and unique_by: together; unique_by: alone says what to compare"
+        end
+
+        option = unique ? "unique:" : "unique_by: #{unique_by.inspect}"
+        unless type.limits.include?(:unique)
+          hint = ("; a Hash's keys are unique already" if type.limits.include?(:not_empty))
+          raise DefinitionError, "#{option} limits only an Array, not #{type}#{hint}"
+        end
+        element = Limits.array_of(type).element
+        unique ? check_unique_entries(element, type) : check_unique_by_entries(element, type)
+      end
+
+      # `Kernel#hash` is identity: no two entries would ever match, so the limit would check nothing.
+      def check_unique_entries(element, type)
+        element = element.inner if element.is_a?(Type::Optional)
+        return unless element.is_a?(Type::ClassRef) && element.klass.instance_method(:hash).owner == Kernel
+
+        raise DefinitionError, "unique: on #{type} compares the entries by identity, as #{element} defines no " \
+                               "eql? and hash, so no two ever match; say what to compare with unique_by:"
+      end
+
+      def check_unique_by_entries(element, type)
+        return unless unique_by.is_a?(Symbol)
+        unless element.is_a?(Type::ClassRef)
+          raise DefinitionError, "#{unique_by.inspect} reads a property of each entry, so unique_by: takes it " \
+                                 "on an Array of a class, not #{type}; a Proc takes any entry"
+        end
+
+        klass = element.klass
+        names = Plan.property_names(klass, Plan.shape_for(klass))
+        return if names.include?(unique_by)
+
+        guesses = DidYouMean::SpellChecker.new(dictionary: names).correct(unique_by)
+        fix = guesses.empty? ? "; #{element} has #{names.join(", ")}" : ", did you mean #{guesses.join(" or ")}?"
+        raise DefinitionError, "unique_by: #{unique_by.inspect} names no property of #{element}#{fix}"
+      end
+
+      def check_in_against(type)
+        allowed = self.in
+        unless allowed.nil? || type.limits.include?(:in)
+          raise DefinitionError, "in: #{allowed.inspect} cannot limit #{type}"
+        end
+        return unless allowed.is_a?(Range) && !numeric_range?(allowed, type)
+
+        raise DefinitionError,
+              "in: #{allowed.inspect} is a range, so it limits only a number with number ends, not #{type}"
+      end
+
+      def numeric_range?(range, type)
+        type.numeric? && [range.begin, range.end].all? { |end_| end_.nil? || end_.is_a?(Numeric) }
+      end
+    end
+  end
+end

data/lib/typemap/mapper/name_resolver.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Typemap
+  class Mapper
+    # Resolves a constant name written in a type — `Integer`, `Size`, `Tuile::Size`, `::Size` —
+    # the way Ruby resolves it in the code beside it: a leading `::` is absolute, anything else is
+    # looked up from the declaring namespace outward (`UI::Foo::Size`, then `UI::Size`, then
+    # `Size`). Qualified names are allowed, never required. Inheritance is not searched, only the
+    # lexical scopes.
+    #
+    # @api private
+    module NameResolver
+      # @param name [String] the name as written, `"Size"`, `"Tuile::Size"`, `"::Size"`
+      # @param namespace [String, nil] the declaring class's full name, `nil` for the top level
+      # @return [Module] the constant
+      # @raise [DefinitionError] if no scope defines it
+      def self.resolve(name, namespace)
+        return lookup(Object, name.delete_prefix("::")) || unknown(name) if name.start_with?("::")
+
+        scopes = namespace.to_s.split("::")
+        scopes.length.downto(0) do |depth|
+          base = depth.zero? ? Object : lookup(Object, scopes.first(depth).join("::"))
+          found = base && lookup(base, name)
+          return found if found
+        end
+        unknown(name)
+      end
+
+      # @param base [Module]
+      # @param path [String] `"A::B"`, looked up segment by segment without inheritance
+      # @return [Module, nil]
+      def self.lookup(base, path)
+        path.split("::").reduce(base) do |mod, segment|
+          return nil unless mod.is_a?(Module) && mod.const_defined?(segment, false)
+
+          mod.const_get(segment, false)
+        end
+      end
+
+      # @raise [DefinitionError]
+      def self.unknown(name)
+        raise DefinitionError, "unknown constant #{name}"
+      end
+    end
+  end
+end

data/lib/typemap/mapper/plan.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Typemap
+  class Mapper
+    # One mappable property: its name, its {Type}, its {Limits}, and whether `required:` was given.
+    #
+    # @!attribute [r] name
+    #   @return [Symbol]
+    # @!attribute [r] type
+    #   @return [Object] a {Type}
+    # @!attribute [r] limits
+    #   @return [Limits]
+    # @!attribute [r] required
+    #   @return [Boolean] `constrain required: true`: a loaded or dumped object must not hold `nil`
+    #
+    # @api private
+    Property = Data.define(:name, :type, :limits, :required)
+
+    # What the mapper knows about one class, worked out once — when the class is first read —
+    # and checked then, whatever a file will hold: the shape, every property with its type and
+    # limits, and the bare `new`'s values. Building it raises {DefinitionError} for a class that
+    # cannot be mapped.
+    #
+    # A data class with a required keyword has no bare `new`: {#check_default} runs on each
+    # load's base instead.
+    #
+    # @!attribute [r] klass
+    #   @return [Class]
+    # @!attribute [r] shape
+    #   @return [Module] {DataShape} or {AccessorShape}
+    # @!attribute [r] properties
+    #   @return [Array<Property>] in declaration order
+    # @!attribute [r] required_keywords
+    #   @return [Array<Symbol>] the keywords a data class cannot build without; a load with no base
+    #     must find each in the file
+    # @!attribute [r] unknown
+    #   @return [Symbol, nil] the class's `unknown` policy, `:raise` or `:ignore`; `nil` follows
+    #     `load`'s `unknown:`
+    #
+    # @api private
+    Plan = Data.define(:klass, :shape, :properties, :required_keywords, :unknown) do
+      # @param klass [Class]
+      # @param types [#type_for] the mapper's type strategy
+      # @return [Plan]
+      # @raise [DefinitionError]
+      def self.build(klass, types)
+        raise DefinitionError, "#{klass.inspect} is not a class" unless klass.is_a?(Class)
+
+        shape = shape_for(klass)
+        names = property_names(klass, shape)
+        constraints = Constrain.constraints_for(klass)
+        stray = constraints.keys - names
+        raise DefinitionError, "#{klass}: constrain names #{stray.join(", ")}, not a property" unless stray.empty?
+
+        shape.check_required_option(klass, constraints.select { |_, constraint| constraint.required }.keys)
+        required_keywords = shape.required_keywords(klass, names)
+        default = bare_new(klass) if required_keywords.empty?
+        properties = names.map { |name| property(klass, name, constraints[name], types) }
+        plan = new(klass: klass, shape: shape, properties: properties, required_keywords: required_keywords,
+                   unknown: Constrain.unknown_for(klass))
+        plan.check_default(default) if default
+        plan
+      end
+
+      # @param klass [Class]
+      # @return [Module] {DataShape} or {AccessorShape}
+      def self.shape_for(klass) = klass < Data ? DataShape : AccessorShape
+
+      # @raise [DefinitionError] unless `klass.new` works with no arguments
+      def self.bare_new(klass)
+        klass.new
+      rescue ArgumentError => e
+        raise DefinitionError, "#{klass}: must build with a bare new, its default instance (#{e.message})"
+      end
+
+      # @param klass [Class]
+      # @param shape [Module] {DataShape} or {AccessorShape}
+      # @return [Array<Symbol>] the mapped properties, `ignore`d ones left out
+      # @raise [DefinitionError] on an `ignore` naming no property, or no property left
+      def self.property_names(klass, shape)
+        all = shape.properties(klass)
+        ignored = Constrain.ignored_for(klass)
+        stray = ignored - all
+        raise DefinitionError, "#{klass}: ignore names #{stray.join(", ")}, not a property" unless stray.empty?
+
+        names = all - ignored
+        raise DefinitionError, "#{klass} has no properties: neither a data class nor an accessor class" if names.empty?
+
+        names
+      end
+
+      def self.property(klass, name, constraint, types)
+        type = types.type_for(klass, name, constraint)
+        limits = if constraint
+                   Limits.new(in: constraint.in, format: constraint.format,
+                              not_blank: constraint.not_blank || false, not_empty: constraint.not_empty || false,
+                              unique: constraint.unique || false, unique_by: constraint.unique_by)
+                 else
+                   Limits.none
+                 end
+        limits.check_against(type)
+        required = constraint&.required || false
+        if required && !type.accepts?(nil)
+          raise DefinitionError, "required: on #{type}, which can never be missing; required: takes a " \
+                                 "#{type}? defaulting to nil"
+        end
+        Property.new(name: name, type: type, limits: limits, required: required)
+      rescue DefinitionError => e
+        raise DefinitionError, "#{klass}##{name}: #{e.message}"
+      end
+
+      # Checks the values of a default instance — the bare `new`, or a load's base built from the
+      # required keywords alone — against their types and limits; a required keyword's value is
+      # the file's, so it is left to the load.
+      #
+      # @param default [Object] an instance of {#klass}
+      # @return [void]
+      # @raise [DefinitionError] naming `Klass#property`
+      def check_default(default)
+        properties.each do |property|
+          next if required_keywords.include?(property.name)
+
+          value = shape.read(default, property.name)
+          check_default_value(property, value)
+        rescue DefinitionError => e
+          raise DefinitionError, "#{klass}##{property.name}: #{e.message}"
+        end
+      end
+
+      # @return [Array<Class>] the classes of nested properties, to be planned too
+      def nested_classes = properties.flat_map { |property| property.type.nested_classes }.uniq
+
+      # @return [Array<Symbol>]
+      def names = properties.map(&:name)
+
+      # Whether `raw` is a table meant for {#klass}, however broken: a Hash that is empty or has
+      # one of its keys. Gates the `[[server]]` / `[server]` hints, which a half-written table
+      # needs most — a test of whether it loads would drop them right there.
+      #
+      #   { "id" => "a", "url" => 3 }   # an entry of Server, with a wrong type
+      #   { "port" => 1 }               # no entry
+      #
+      # @param raw [Object]
+      # @return [Boolean]
+      def entry_like?(raw)
+        raw.is_a?(Hash) && (raw.empty? || raw.keys.map(&:to_s).intersect?(names.map(&:to_s)))
+      end
+
+      # @param base [Object] an instance of {#klass}, supplying every value not loaded; never changed
+      # @param loaded [Hash{Symbol => Object}] the values read from the file
+      # @return [Object] a new instance
+      def build(base, loaded)
+        shape == DataShape ? shape.build(klass, base, loaded) : shape.build(klass, base, loaded, names)
+      end
+
+      private
+
+      def check_default_value(property, value)
+        if property.required && !value.nil?
+          raise DefinitionError, "required: its default must be nil, so a file that leaves the key out fails, " \
+                                 "not #{value.inspect}"
+        end
+        unless property.type.accepts?(value)
+          raise DefinitionError, "its default #{value.inspect} does not fit #{property.type}"
+        end
+
+        property.limits.check(value, "")
+        property.limits.check_unique(value, property.type, "", nil)
+      rescue DataError => e
+        raise DefinitionError, "its default #{e.message}"
+      end
+    end
+  end
+end