versponse 0.1.0 → 0.2.0

data/Rakefile

@@ -1,12 +1,35 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-require "minitest/test_task"
+require "rake/testtask"
 
-Minitest::TestTask.create
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.warning = true
+end
 
 require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-task default: %i[test rubocop]
+desc "Check YARD documentation coverage (must be 100%)"
+task :yard do
+  require "yard"
+
+  stats = YARD::CLI::Stats.new
+  stats.run("--list-undoc")
+  undocumented = stats.instance_variable_get(:@undoc_list) || []
+
+  abort "\nYARD documentation check failed: #{undocumented.size} undocumented objects found." unless undocumented.empty?
+
+  puts "\nYARD documentation: 100% documented"
+end
+
+desc "Benchmark versponse against alba and blueprinter"
+task :bench do
+  ruby "-Ilib", "bench/serializers.rb"
+end
+
+task default: %i[test rubocop yard]

data/lib/versponse/base/class_methods.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Public class methods of {Versponse::Base}
+  module Base::ClassMethods
+    # Context used when serialize gets none (avoids two allocations per call)
+    EMPTY_CONTEXT = {}.freeze
+
+    # Versions, resolution and caches of the class
+    #
+    # @return [Versponse::Internals] per-class internals
+    # @api private
+    def versponse
+      @versponse ||= Internals.new(self)
+    end
+
+    # Renders an object, or each item of an Array-like collection, to a Hash with String keys
+    #
+    # @param object [Object, Hash, #to_ary, Set] source
+    # @param version [String, nil] requested version, config.current_version when nil
+    # @param view [Symbol] view name
+    # @param context [Hash, nil] passed to blocks and conditions; nil for none
+    # @param root [String, Symbol, nil] wraps the result under this key
+    # @param meta [Hash, nil] added under "meta" with String keys (requires root:)
+    # @return [Hash, Array<Hash>] rendered output
+    # @param expand [Array<String, Symbol>, nil] dotted paths of expandable associations to expand, or "*"
+    # @param fields [Array<String, Symbol>, nil] dotted paths of the fields to render (identifiers and consts always
+    #   render), "*" or nil for all
+    # @raise [ArgumentError] without a version or with meta: but no root:
+    # @raise [Versponse::InvalidExpandError] for unknown expand paths (config.unknown_expand = :raise)
+    # @raise [Versponse::InvalidFieldsError] for unknown paths or paths below unexpanded associations
+    #   (config.unknown_fields = :raise)
+    # @raise [Versponse::VersionNotFoundError] when no declared version matches, or supported_versions leaves it out
+    # @raise [Versponse::ViewNotFoundError] for an unknown or nil view
+    # @raise [Versponse::ExtractionError] when reading a value fails
+    def serialize(object, version: nil, view: :default, context: EMPTY_CONTEXT, root: nil, meta: nil, expand: nil, fields: nil)
+      raise ArgumentError, "meta: requires root:" if meta && root.nil?
+      raise ViewNotFoundError, "view: can't be nil; the default view is :default" if view.nil?
+
+      context ||= EMPTY_CONTEXT
+      internals = versponse
+      internals.requesting(version) do |canonical|
+        expansion = internals.expansion(expand, version: canonical, view:)
+        selection = internals.selection(fields, version: canonical, view:, expansion:) unless fields.nil?
+        context = context.frozen? ? context : context.dup.freeze
+        validate = Versponse.configuration.validate_output && OutputValidator.enabled?(self)
+        if selection && !selection.all?
+          # Validating plans prove the full shape, so a selection renders with the plain plan
+          data = render(object, internals.plan(version: canonical, view:), context, Selection::Scope.new(expansion, selection))
+          OutputValidator.call(self, data, version: canonical, view:, selection:) if validate
+        # A validating plan checks while rendering; the output goes through OutputValidator only when a check failed
+        elsif validate && (inline = internals.validating_plan(version: canonical, view:))
+          data = nil
+          failed = InlineValidation.run { data = render(object, inline, context, expansion) }
+          OutputValidator.call(self, data, version: canonical, view:) if failed
+        else
+          # The plain plan is looked up only here and for a selection, so a validated render skips it; render is
+          # written out: the extra call costs about 2% of a small render in the interpreter
+          plan = internals.plan(version: canonical, view:)
+          data = Collections.collection?(object) ? Collections.map(Collections.items(object)) { |item| plan.call(item, context, expansion) } : plan.call(object, context, expansion)
+          OutputValidator.call(self, data, version: canonical, view:) if validate
+        end
+        Wrapper.wrap(data, root:, meta:)
+      end
+    end
+
+    # @param object [Object] source
+    # @param options [Hash] see {#serialize}
+    # @return [String] JSON produced by config.json_generator
+    def serialize_json(object, **options)
+      Versponse.configuration.json_generator.call(serialize(object, **options))
+    end
+
+    # OpenAPI schema with $refs to other components, or a root/meta wrapper schema
+    #
+    # @param version [String, nil] requested version, config.current_version when nil
+    # @param view [Symbol] view name
+    # @param root [String, Symbol, nil] builds a wrapper schema with the response under this key
+    # @param meta [Class, nil] class whose $ref describes "meta" (requires root:)
+    # @param collection [Boolean] the root key holds an array
+    # @return [Hash] frozen schema
+    # @raise [ArgumentError] with meta: but no root:
+    # @raise [Versponse::DefinitionError] for a meta: that isn't a class with a $ref
+    # @raise [Versponse::VersionNotFoundError] when the class, or a Versponse meta: class, doesn't serve the version
+    # @raise [Versponse::ViewNotFoundError] for an unknown view (wrappers too)
+    def to_schema(version: nil, view: :default, root: nil, meta: nil, collection: false)
+      Wrapper.check_meta!(meta)
+      raise ArgumentError, "meta: requires root:" if meta && root.nil?
+
+      versponse.requesting(version) do |canonical|
+        next versponse.openapi_schema(version: canonical, view:) unless root
+
+        # The wrapper only refers to the components, but their versions and the view must exist like for any schema
+        versponse.resolve(canonical).properties_for(view)
+        meta.versponse.resolve(canonical) if References.versponse?(meta)
+        DeepFreeze.call(Wrapper.schema(self, view:, root:, meta:, collection:))
+      end
+    end
+
+    # Schema with every reference inlined, for validation
+    #
+    # @param version [String, nil] requested version, config.current_version when nil
+    # @param view [Symbol] view name
+    # @param property [Symbol, String, nil] returns only this property's schema
+    # @return [Hash] frozen schema
+    # @raise [Versponse::PropertyNotFoundError] for an unknown property
+    def to_validation_schema(version: nil, view: :default, property: nil)
+      versponse.requesting(version) do |canonical|
+        next versponse.property_validation_schema(version: canonical, view:, key: property.to_s) if property
+
+        versponse.validation_schema(version: canonical, view:)
+      end
+    end
+
+    # Component name without the view suffix: the class name without its first namespace, squashed.
+    # Override it to rename components (e.g. strip a "Response" suffix).
+    #
+    # @return [String] base component name
+    def base_component_name
+      name.to_s.split("::", 2).last.to_s.delete(":")
+    end
+
+    # @param view [Symbol] view name
+    # @return [String] component name, with the PascalCase view name for non-default views
+    def component_name(view: :default)
+      (view.to_sym == :default) ? base_component_name : base_component_name + Naming.pascalize(view)
+    end
+
+    # @param view [Symbol] view name
+    # @param property [Symbol, String, nil] points at one property
+    # @return [String] "#/components/schemas/<name>" reference
+    # @raise [Versponse::DefinitionError] for an anonymous class, which has no component name
+    def to_ref(view: :default, property: nil)
+      raise DefinitionError, "anonymous response classes have no component; name the class or override base_component_name" if base_component_name.empty?
+
+      base = "#/components/schemas/#{component_name(view:)}"
+      property ? "#{base}/properties/#{property}" : base
+    end
+
+    # Every expandable dotted path of a response, for scope checks and expand: validation
+    #
+    # @param version [String, nil] requested version, config.current_version when nil
+    # @param view [Symbol] view name
+    # @return [Array<String>] sorted, frozen paths such as ["deal.stage", "site"]
+    def expandable_paths(version: nil, view: :default)
+      versponse.requesting(version) { |canonical| versponse.expandable_paths(version: canonical, view:) }
+    end
+
+    # The response classes each expandable path renders, for metadata such as scopes declared on the classes
+    #
+    # @param version [String, nil] requested version, config.current_version when nil
+    # @param view [Symbol] view name
+    # @return [Hash{String => Array<Class>}] frozen, keyed like expandable_paths: a reference's from:, a
+    #   collection's item: or every one_of variant's class, such as {"site" => [SiteResponse]}
+    def expandable_targets(version: nil, view: :default)
+      versponse.requesting(version) { |canonical| versponse.expandable_targets(version: canonical, view:) }
+    end
+
+    # Every dotted path serialize fields: accepts, for docs and scope checks
+    #
+    # @param version [String, nil] requested version, config.current_version when nil
+    # @param view [Symbol] view name
+    # @return [Array<String>] sorted, frozen paths such as ["id", "site", "site.name"]
+    def selectable_paths(version: nil, view: :default)
+      versponse.requesting(version) { |canonical| versponse.selectable_paths(version: canonical, view:) }
+    end
+
+    private
+
+    # @param object [Object] source, or a collection of them
+    # @param plan [#call] plan of one object
+    # @param context [Hash] frozen serialize context
+    # @param expansion [Versponse::Expansion, Versponse::Selection::Scope] expand tree, paired with the selection in a
+    #   selected render
+    # @return [Hash, Array<Hash>] rendered output
+    def render(object, plan, context, expansion)
+      Collections.collection?(object) ? Collections.map(Collections.items(object)) { |item| plan.call(item, context, expansion) } : plan.call(object, context, expansion)
+    end
+  end
+end

data/lib/versponse/base/dsl.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Class-level DSL of {Versponse::Base}. All methods are private class methods; they delegate to the
+  # class's {Versponse::Builder}, which holds the definition state.
+  module Base::DSL
+    private
+
+    # Sets the description of the class or the current version
+    #
+    # @param text [String] description
+    # @return [void]
+    def description(text)
+      versponse.builder.description(text)
+    end
+
+    # Adds schema keywords to the class or the current version
+    #
+    # @param options [Hash] JSON Schema keywords in snake_case
+    # @return [void]
+    def schema_options(**options)
+      versponse.builder.schema_options(**options)
+    end
+
+    # Limits the versions the class serves; resolving a version outside the range raises
+    # VersionNotFoundError. Subclasses inherit the range; no arguments removes an inherited one.
+    #
+    # @param min [String, nil] first supported version (inclusive), defaults to the first declared version
+    # @param max [String, nil] last supported version (inclusive), defaults to no upper bound
+    # @return [void]
+    # @raise [Versponse::DefinitionError] when min sorts after max, inside a version, or after the first version
+    def supported_versions(min: nil, max: nil)
+      versponse.builder.supported_versions(min:, max:)
+    end
+
+    # Sets the fraction digits of date-time values, replacing the date-time formatter of config.formatters.
+    # With from:, it applies from that version on. Subclasses inherit the settings and can add or replace them.
+    #
+    # @param digits [Integer] fraction digits from 0 (whole seconds) to 9
+    # @param from [String, nil] first version it applies to; nil for every version without a later setting
+    # @return [void]
+    # @raise [Versponse::DefinitionError] inside a version, after the first version, for invalid digits,
+    #   or when the class already sets the precision from that version
+    def time_precision(digits, from: nil)
+      versponse.builder.time_precision(digits, from:)
+    end
+
+    # Replaces nil values of the class's field, enum and array properties without default:. Subclasses inherit it.
+    #
+    # @param callable [#call, nil] called with (object, key, context); nil removes an inherited one
+    # @return [void]
+    # @raise [Versponse::DefinitionError] inside a version, after the first version, or for a value that can't take
+    #   (object, key, context)
+    def on_nil(callable)
+      versponse.builder.on_nil(callable)
+    end
+
+    # Policy for the class's failing properties without their own on_error:. Subclasses inherit it.
+    #
+    # @param policy [Symbol, #call, nil] :raise, :nullify, :omit, a handler called with (error, object, key, context),
+    #   or nil to remove an inherited one
+    # @return [void]
+    # @raise [Versponse::DefinitionError] inside a version, after the first version, or for an unknown policy
+    def on_error(policy)
+      versponse.builder.on_error(policy)
+    end
+
+    # Declares a version
+    #
+    # @param name [String] version name, compared as a String
+    # @param inherit [Boolean, String, Symbol] true copies the previously declared version, a name copies the
+    #   closest version at or before it
+    # @param exclude_properties [Array<Symbol>] inherited properties to leave out
+    # @return [void]
+    # @raise [Versponse::DefinitionError] when nested in another version
+    # @raise [Versponse::DefinitionError] when inherit: names a version before every declared one
+    def version(name, inherit: true, exclude_properties: [], &block)
+      versponse.builder.version(name, inherit:, exclude_properties:, &block)
+    end
+
+    # Computes the value of the enclosing inline object, inline collection or one_of
+    #
+    # @yieldparam object [Object] serialized object
+    # @yieldparam context [Hash] serialize context
+    # @return [void]
+    def source(&block)
+      versponse.builder.source(&block)
+    end
+
+    # Declares a scalar field
+    #
+    # @param name [Symbol] output key
+    # @param type [Symbol, Array<Symbol>] string, number, integer, boolean, object, a custom type, or a union like [:integer, :string]
+    # @param options [Hash] map:, nullable:, if:, unless:, JSON Schema keywords
+    # @yieldparam object [Object] serialized object
+    # @yieldparam context [Hash] serialize context
+    # @return [void]
+    def field(name, type: nil, **options, &block)
+      versponse.builder.field(name, type:, **options, &block)
+    end
+
+    # Declares a field of both the full shape and the collapsed shape, rendered for expandable associations that aren't expanded
+    #
+    # @param name [Symbol] output key
+    # @param type [Symbol, nil] field type (with_options type:, else :string)
+    # @param collapse_if [Proc, #call, nil] (not taken from with_options) called with (object) or (object, context); when it returns false the
+    #   association renders in full instead (a collection item: when it is false for any item), and the full shape leaves this field out.
+    #   One per version.
+    # @param options [Hash] map:, nullable:, description: and JSON Schema keywords (no if:/unless:); with_options defaults apply
+    # @return [void]
+    # @raise [Versponse::DefinitionError] outside a version, with if:/unless:, or with a collapse_if: that doesn't respond to call
+    def identifier(name, type: nil, collapse_if: nil, **options, &block)
+      versponse.builder.identifier(name, type:, collapse_if:, **options, &block)
+    end
+
+    # Declares a value from a fixed list
+    #
+    # @param name [Symbol] output key
+    # @param type [Symbol, Array<Symbol>, nil] type of the values, as for {#field} (with_options type:); inferred from the values when nil
+    # @param values [Array] allowed values, each of the type
+    # @param options [Hash] see {#field}
+    # @return [void]
+    # @raise [Versponse::DefinitionError] when the type can't be inferred, or a value isn't of the type
+    def enum(name, values:, type: nil, **options, &block)
+      versponse.builder.enum(name, values:, type:, **options, &block)
+    end
+
+    # Declares a constant
+    #
+    # @param name [Symbol] output key
+    # @param value [Object] constant value
+    # @param options [Hash] if:, unless:, JSON Schema keywords
+    # @return [void]
+    # @raise [Versponse::DefinitionError] with a block, map: or nullable: (a constant never reads the object)
+    def const(name, value:, **options, &block)
+      versponse.builder.const(name, value:, **options, &block)
+    end
+
+    # Declares an array of scalars
+    #
+    # @param name [Symbol] output key
+    # @param type [Symbol, Array<Symbol>] item type, or a union like [:integer, :string]
+    # @param item_schema_options [Hash] JSON Schema keywords of each item
+    # @param options [Hash] see {#field}
+    # @return [void]
+    def array(name, type: nil, item_schema_options: {}, **options, &block)
+      versponse.builder.array(name, type:, item_schema_options:, **options, &block)
+    end
+
+    # Declares an inline object; the block defines its properties
+    #
+    # @param name [Symbol] output key
+    # @param options [Hash] map: (use "." for the same object), nullable:, if:, unless:, JSON Schema keywords
+    # @return [void]
+    def object(name, **options, &block)
+      versponse.builder.object(name, **options, &block)
+    end
+
+    # Declares an array of objects, either of another response class (item:) or inline (block)
+    #
+    # With item:, a block computes the value. Without item:, the block defines the item properties.
+    #
+    # @param name [Symbol] output key
+    # @param item [Class, nil] class implementing the reference protocol
+    # @param view [Symbol, nil] view of item (with_options view:, else :default)
+    # @param options [Hash] see {#field}
+    # @return [void]
+    def collection(name, item: nil, view: nil, **options, &block)
+      versponse.builder.collection(name, item:, view:, **options, &block)
+    end
+
+    # Declares a nested response class, or a variant inside one_of
+    #
+    # @param name [Symbol, nil] output key, omitted inside one_of
+    # @param from [Class] class implementing the reference protocol
+    # @param view [Symbol, nil] view of from (with_options view:, else :default)
+    # @param property [Symbol, nil] one property of a non-Versponse class's schema
+    # @param match [Class, Proc, nil] one_of matcher, compared with ===
+    # @param options [Hash] see {#field}
+    # @return [void]
+    def reference(name = nil, from:, view: nil, property: nil, match: nil, **options, &block)
+      versponse.builder.reference(name, from:, view:, property:, match:, **options, &block)
+    end
+
+    # Declares a polymorphic value; the block declares variants with reference from:, match:.
+    # Without a name, inside a collection block, it types each item of the collection.
+    #
+    # @param positional_name [Symbol, nil] output key; nil for the item one_of of a collection
+    # @param name [Symbol, nil] the output key as a keyword, as verquest writes it
+    # @param discriminator [String, Symbol, nil] OpenAPI discriminator property
+    # @param options [Hash] see {#field}; an item one_of takes only nullable: and schema keywords
+    # @return [void]
+    # @raise [Versponse::DefinitionError] when the name is given both ways
+    def one_of(positional_name = nil, name: nil, discriminator: nil, **options, &block)
+      versponse.builder.one_of(positional_name, name:, discriminator:, **options, &block)
+    end
+
+    # Declares a view inside a version
+    #
+    # @param name [Symbol] view name
+    # @return [void]
+    def view(name, &block)
+      versponse.builder.view(name, &block)
+    end
+
+    # Applies another view's operations inside a view
+    #
+    # @param name [Symbol] included view
+    # @return [void]
+    def include_view(name)
+      versponse.builder.include_view(name)
+    end
+
+    # Removes properties from the current version or view
+    #
+    # @param names [Array<Symbol>] property names
+    # @return [void]
+    def exclude_properties(*names)
+      versponse.builder.exclude_properties(*names)
+    end
+
+    # Applies options to every property declared in the block. A nested with_options replaces the outer
+    # options, and map: is ignored, as in verquest.
+    #
+    # @param options [Hash] shared options
+    # @return [void]
+    def with_options(**options, &block)
+      versponse.builder.with_options(**options, &block)
+    end
+  end
+end

data/lib/versponse/base.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Parent of every response definition
+  #
+  # @example
+  #   class UnitTypeResponse < Versponse::Base
+  #     version "2025-09" do
+  #       field :id, type: :string, map: "public_id"
+  #       reference :site, from: SiteResponse, view: :embedded
+  #
+  #       view :embedded do
+  #         exclude_properties :site
+  #       end
+  #     end
+  #   end
+  class Base
+    extend DSL
+    extend ClassMethods
+
+    # Registers the subclass for {Versponse.components} and {Versponse.reset_caches!}
+    #
+    # @param subclass [Class] new response class
+    # @return [void]
+    # @raise [Versponse::DefinitionError] when the parent already declares versions
+    def self.inherited(subclass)
+      super
+      if self != Versponse::Base && !versponse.versions.empty?
+        raise DefinitionError, "#{name} has versions and can not be subclassed; subclass a class without versions (e.g. an abstract BaseResponse)"
+      end
+
+      Registry.add(subclass)
+    end
+  end
+end