kiosk-test-support 0.5.20

data/lib/kiosk/test_helpers/conformance/in_process_origin.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+# Needs kiosk-server, which only a Rails host carries; this gem does not depend
+# on it, so a test helper requires this file explicitly:
+#   require "kiosk/test_helpers/conformance/in_process_origin"
+#   require "kiosk/test_helpers/conformance/rspec"     # or .../minitest
+#   Kiosk::TestHelpers::Conformance.origin = Kiosk::TestHelpers::Conformance::InProcessOrigin.new
+require 'securerandom'
+
+require 'kiosk/server'
+require 'kiosk/test_helpers/conformance'
+require 'kiosk/test_helpers/in_process_wire'
+
+module Kiosk
+  module TestHelpers
+    module Conformance
+      # The origin the conformance checks run against: the booted app's own
+      # registries, routes and validators. A call goes through the verb's route
+      # as an assistant's does, with a token the origin signs for the principal.
+      # Calls do not roll back; undoing writes is the test framework's job.
+      class InProcessOrigin
+        # @param app [#call] the Rack app a call goes through; defaults to `Rails.application`
+        # @param routes [ActionDispatch::Routing::RouteSet] defaults to `Rails.application.routes`
+        def initialize(app: nil, routes: nil)
+          @wire   = InProcessWire.new(app: app)
+          @routes = routes
+        end
+
+        def mount_path = Kiosk.configuration.mount_path
+
+        # Not memoised: development rebuilds the registry at `to_prepare`.
+        def verbs
+          descriptors(Kiosk::Server::Queries, :query) + descriptors(Kiosk::Server::Actions, :action)
+        end
+
+        # The action a request reaches, as `{controller:, action:, kiosk_verb:}`; nil when no route answers.
+        def recognize(path, method:)
+          verb_route(path, method.to_s.upcase) ||
+            route_set.recognize_path(path, method: method.to_s.downcase.to_sym).slice(:controller, :action, :kiosk_verb)
+        rescue ActionController::RoutingError
+          nil
+        end
+
+        def call(name, kind:, params:, as: nil)
+          @wire.call(name, kind: kind, params: params, identity: identity_for(as))
+        end
+
+        # Uses the wire's own validators, so a query's reserved `limit`/`cursor` pass as they do on the wire.
+        def schema_errors(payload, schema:, verb:, kind:, slot:)
+          if slot.to_s == 'input_schema'
+            Kiosk::Server::RequestValidation.validate_arguments!(payload, input_schema: schema, verb: verb,
+                                                                          query: kind == :query)
+          else
+            Kiosk::Server::ResponseValidation.validate_payload!(payload, output_schema: schema, verb: verb,
+                                                                         kind: kind)
+          end
+          []
+        rescue Kiosk::Server::Errors::Base => e
+          ["#{slot}: #{e.message}"]
+        end
+
+        # A record contributes its `#id`; anything else is the principal id itself.
+        def identity_for(subject, role: nil)
+          raise ArgumentError, NO_PRINCIPAL if subject.nil?
+
+          Kiosk::Identity.new(
+            user_id: subject.respond_to?(:id) ? subject.id : subject,
+            role: resolve_role(subject, role), actor: 'agent', agent_id: SecureRandom.uuid
+          )
+        end
+
+        NO_PRINCIPAL =
+          'a conformance call needs a principal — pass `as:` a record or a principal id. ' \
+          'Every verb is served behind authentication, so there is no anonymous call ' \
+          'to make.'
+        private_constant :NO_PRINCIPAL
+
+        private
+
+        def descriptors(registry, kind)
+          registry.catalog.map do |descriptor|
+            Verb.new(
+              name: descriptor[:name], kind: kind, reach: descriptor[:reach],
+              input_schema: descriptor[:input_schema], output_schema: descriptor[:output_schema],
+              example_params: descriptor[:example_params], endpoint: endpoint(registry.fetch(descriptor[:name]))
+            )
+          end
+        end
+
+        # The action that answers the verb: its own, or the engine's verb endpoint.
+        def endpoint(handler)
+          controller = handler.controller if handler.is_a?(Kiosk::Server::ControllerVerb)
+          "#{controller.controller_path}##{handler.method_name}" if controller
+        end
+
+        # The verb route `kiosk do` drew at `path`, as the action it reaches.
+        def verb_route(path, method)
+          route = route_set.routes.find { |r| verb_route?(r) && r.verb == method && r.path.match(path) }
+          return unless route
+
+          controller, action = route.app.app.endpoint.split('#')
+          { controller: controller, action: action, kiosk_verb: route.app.app.name }
+        end
+
+        def verb_route?(route)
+          route.app.respond_to?(:app) && route.app.app.is_a?(Kiosk::Server::Routing::VerbRoute)
+        end
+
+        def route_set = @routes || ::Rails.application.routes
+
+        def resolve_role(subject, explicit)
+          return explicit.to_s if explicit
+          return subject.role.to_s if subject.respond_to?(:role) && subject.role
+
+          roles = Kiosk.configuration.roles
+          roles.first.to_s if roles && !roles.empty?
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/test_helpers/conformance/minitest.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'minitest/assertions'
+
+require 'kiosk/test_helpers/conformance'
+
+module Kiosk
+  module TestHelpers
+    module Conformance
+      # Minitest assertions for the four conformance checks; required by name only.
+      # Each returns its {Outcome}.
+      module Assertions
+        def assert_kiosk_verbs_routed(message = nil, origin: nil)
+          kiosk_conformance!(Conformance.routes(kiosk_conformance_origin(origin)), message)
+        end
+
+        def assert_kiosk_verb_executes(name, params: Checks::EXAMPLE, as: nil,
+                                       message: nil, origin: nil)
+          kiosk_conformance!(
+            Checks.executes(kiosk_conformance_origin(origin), name, params: params, as: as),
+            message
+          )
+        end
+
+        def assert_kiosk_answer_matches_declared_schema(name, params: Checks::EXAMPLE, as: nil,
+                                                        message: nil, origin: nil)
+          kiosk_conformance!(
+            Checks.declared_shape(kiosk_conformance_origin(origin), name, params: params, as: as),
+            message
+          )
+        end
+
+        # rubocop:disable-next Metrics/ParameterLists -- public assertion signature; every keyword is part of it
+        def assert_kiosk_scoped_to_principal(name, as:, and_not:, params: Checks::EXAMPLE,
+                                             message: nil, origin: nil)
+          kiosk_conformance!(
+            Checks.principal_scope(kiosk_conformance_origin(origin), name,
+                                   as: as, and_not: and_not, params: params),
+            message
+          )
+        end
+
+        private
+
+        # `assert` rather than `flunk`, so a passing check is counted.
+        def kiosk_conformance!(outcome, message)
+          assert(outcome.ok?, message || outcome.message)
+          outcome
+        end
+
+        def kiosk_conformance_origin(explicit)
+          explicit || Conformance.require_origin!
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/test_helpers/conformance/null_origin.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'kiosk/test_helpers/conformance/verb'
+
+module Kiosk
+  module TestHelpers
+    module Conformance
+      # A hand-built origin with no Rails, Postgres or engine; this gem's own
+      # suite runs the checks against it. The origin contract:
+      #
+      #   #mount_path                       → String, e.g. "/kiosk"
+      #   #verbs                            → Array<Verb>
+      #   #recognize(path, method:)         → {controller:, action:, kiosk_verb:} or nil
+      #   #call(name, kind:, params:, as:)  → the verb's answer, or raises
+      #   #schema_errors(payload, schema:, verb:, kind:, slot:) → Array<String> (optional)
+      class NullOrigin
+        attr_reader :mount_path, :verbs, :calls
+
+        # @param routes [Hash] `[method, path] => {controller:, action:, kiosk_verb:}`
+        # @param answers [Hash] `[verb_name, principal]` or `verb_name` => answer; an Exception is raised
+        def initialize(mount_path: '/kiosk', verbs: [], routes: nil, answers: {})
+          @mount_path = mount_path
+          @verbs      = verbs
+          @routes     = routes || self.class.routes_for(mount_path, verbs)
+          @answers    = answers
+          @calls      = []
+        end
+
+        # The route table a correctly routed origin would have.
+        def self.routes_for(mount_path, verbs)
+          verbs.each_with_object({}) do |verb, table|
+            path = "#{mount_path.chomp('/')}/#{verb.name}"
+            controller, action = verb.endpoint.split('#')
+            table[[verb.http_method, path]] = {
+              controller: controller, action: action, kiosk_verb: verb.name
+            }
+          end
+        end
+
+        def recognize(path, method:)
+          @routes[[method.to_s.upcase, path]]
+        end
+
+        def call(name, kind:, params:, as: nil)
+          @calls << { name: name, kind: kind, params: params, as: as }
+          answer = @answers.fetch([name, as]) { @answers.fetch(name, nil) }
+          answer = answer.call(params: params, as: as) if answer.is_a?(Proc)
+          raise answer if answer.is_a?(::Exception)
+
+          answer
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/test_helpers/conformance/outcome.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module TestHelpers
+    module Conformance
+      # The result of one check. A failure is returned, never raised; `message` is
+      # the sentence both adapters render, `details` the facts behind it.
+      Outcome = Data.define(:ok, :check, :subject, :message, :details) do
+        def ok? = ok
+
+        def failed? = !ok
+      end
+
+      def self.pass(check, **) = outcome(true, check, **)
+
+      def self.fail(check, **) = outcome(false, check, **)
+
+      def self.outcome(passed, check, subject: nil, message: '', details: {})
+        Outcome.new(ok: passed, check: check.to_sym, subject: subject,
+                    message: message.to_s, details: details || {})
+      end
+      private_class_method :outcome
+    end
+  end
+end

data/lib/kiosk/test_helpers/conformance/rspec.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'rspec/expectations'
+
+require 'kiosk/test_helpers/conformance'
+
+module Kiosk
+  module TestHelpers
+    module Conformance
+      # RSpec matchers for the four conformance checks; required by name only.
+      module RSpecHelpers
+        def kiosk_origin = Conformance.require_origin!
+      end
+
+      # The matcher DSL hands keywords to a block as one positional Hash.
+      module RSpecOptions
+        module_function
+
+        def origin(options)
+          options[:origin] || Conformance.require_origin!
+        end
+
+        def params(options)
+          options.fetch(:params, Checks::EXAMPLE)
+        end
+      end
+    end
+  end
+end
+
+# `expect(kiosk_origin).to have_a_route_for_every_verb`
+# Without `|options = {}|` a keyword `origin:` would be silently dropped.
+RSpec::Matchers.define :have_a_route_for_every_verb do |options = {}|
+  match do |origin|
+    @outcome = Kiosk::TestHelpers::Conformance::Checks.routes(
+      origin || Kiosk::TestHelpers::Conformance::RSpecOptions.origin(options)
+    )
+    @outcome.ok?
+  end
+
+  failure_message { @outcome.message }
+  failure_message_when_negated { "expected some verb to be unrouted, but #{@outcome.message}" }
+  description { 'have a route for every declared verb' }
+end
+
+# `expect(:catalog).to execute_as_a_kiosk_verb`
+RSpec::Matchers.define :execute_as_a_kiosk_verb do |options = {}|
+  match do |name|
+    @outcome = Kiosk::TestHelpers::Conformance::Checks.executes(
+      Kiosk::TestHelpers::Conformance::RSpecOptions.origin(options), name,
+      params: Kiosk::TestHelpers::Conformance::RSpecOptions.params(options),
+      as: options[:as]
+    )
+    @outcome.ok?
+  end
+
+  failure_message { @outcome.message }
+  failure_message_when_negated { "expected #{@outcome.subject} to refuse, but #{@outcome.message}" }
+  description { 'execute as a Kiosk verb' }
+end
+
+# `expect(:catalog).to answer_its_declared_schema`
+RSpec::Matchers.define :answer_its_declared_schema do |options = {}|
+  match do |name|
+    @outcome = Kiosk::TestHelpers::Conformance::Checks.declared_shape(
+      Kiosk::TestHelpers::Conformance::RSpecOptions.origin(options), name,
+      params: Kiosk::TestHelpers::Conformance::RSpecOptions.params(options),
+      as: options[:as]
+    )
+    @outcome.ok?
+  end
+
+  failure_message { @outcome.message }
+  failure_message_when_negated do
+    "expected #{@outcome.subject} to answer something its own schema rejects, " \
+      "but #{@outcome.message}"
+  end
+  description { 'answer the shape its own output_schema declares' }
+end
+
+# `expect(:my_orders).to be_scoped_to_principal(as: alice, and_not: bob)`
+RSpec::Matchers.define :be_scoped_to_principal do |options = {}|
+  match do |name|
+    @outcome = Kiosk::TestHelpers::Conformance::Checks.principal_scope(
+      Kiosk::TestHelpers::Conformance::RSpecOptions.origin(options), name,
+      as: options.fetch(:as),
+      and_not: options.fetch(:and_not),
+      params: Kiosk::TestHelpers::Conformance::RSpecOptions.params(options)
+    )
+    @outcome.ok?
+  end
+
+  failure_message { @outcome.message }
+  failure_message_when_negated do
+    "expected #{@outcome.subject} to leak across principals, but #{@outcome.message}"
+  end
+  description { 'be scoped to the calling principal' }
+end
+
+RSpec.configure { |config| config.include(Kiosk::TestHelpers::Conformance::RSpecHelpers) } if defined?(RSpec) && RSpec.respond_to?(:configure)

data/lib/kiosk/test_helpers/conformance/verb.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module TestHelpers
+    module Conformance
+      HTTP_METHODS = { query: 'GET', action: 'POST' }.freeze
+
+      # The engine's own endpoints, which answer the verbs the engine serves.
+      WIRE_ENDPOINTS = {
+        query: 'kiosk/server/verb#show',
+        action: 'kiosk/server/verb#create'
+      }.freeze
+
+      # One declared verb, as an origin's descriptor presents it to the checks.
+      # `endpoint` is the `controller#action` that answers it.
+      Verb = Data.define(:name, :kind, :reach, :input_schema, :output_schema, :example_params, :endpoint) do
+        def initialize(name:, kind:, reach: 'principal', endpoint: nil, **schemas)
+          kind = kind.to_sym
+          raise ArgumentError, "kind must be :query or :action, got #{kind.inspect}" unless HTTP_METHODS.key?(kind)
+
+          super(name: name.to_s, kind: kind, reach: (reach || 'principal').to_s,
+                endpoint: endpoint || WIRE_ENDPOINTS.fetch(kind),
+                input_schema: nil, output_schema: nil, example_params: nil, **schemas)
+        end
+
+        def query? = kind == :query
+
+        def http_method = HTTP_METHODS.fetch(kind)
+
+        def other_http_method = HTTP_METHODS.fetch(query? ? :action : :query)
+
+        def to_s = "#{kind} #{name.inspect}"
+      end
+    end
+  end
+end

data/lib/kiosk/test_helpers/conformance.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'kiosk/test_helpers/errors'
+require 'kiosk/test_helpers/conformance/outcome'
+require 'kiosk/test_helpers/conformance/verb'
+require 'kiosk/test_helpers/conformance/checks'
+require 'kiosk/test_helpers/conformance/null_origin'
+
+module Kiosk
+  module TestHelpers
+    # Four checks an origin runs against itself: routes resolve, a verb executes,
+    # an answer matches its declared schema, data access is scoped to the principal.
+    # Set `Conformance.origin`, then require the minitest or rspec adapter.
+    module Conformance
+      class << self
+        # Anything answering the {NullOrigin} contract.
+        attr_accessor :origin
+
+        def require_origin!
+          origin || raise(Errors::OriginNotConfigured)
+        end
+
+        def reset!
+          @origin = nil
+        end
+
+        # The four {Checks} against the configured origin, returning an {Outcome}.
+        def routes(origin = require_origin!)
+          Checks.routes(origin)
+        end
+
+        def executes(name, params: Checks::EXAMPLE, as: nil, origin: require_origin!)
+          Checks.executes(origin, name, params: params, as: as)
+        end
+
+        def declared_shape(name, params: Checks::EXAMPLE, as: nil, origin: require_origin!)
+          Checks.declared_shape(origin, name, params: params, as: as)
+        end
+
+        def principal_scope(name, as:, and_not:, params: Checks::EXAMPLE, origin: require_origin!)
+          Checks.principal_scope(origin, name, as: as, and_not: and_not, params: params)
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/test_helpers/customer.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'jwt'
+require 'kiosk/test_helpers/assistant'
+
+module Kiosk
+  module TestHelpers
+    # What the origin answered: what was asked for, or a refusal with its code
+    # and a hint about what to do instead.
+    class Answer
+      def initialize(response) = @response = response
+
+      def ok? = @response.status.between?(200, 299)
+
+      # A problem document's `code`, or an OAuth `error` such as `authorization_pending`.
+      def refused?(code) = !ok? && [@response.body['code'], @response.body['error']].include?(code.to_s)
+
+      def hint = @response.body['hint'].to_s
+      def detail = @response.body['detail'].to_s
+      def [](key) = @response.body[key.to_s]
+      def rows = @response.body
+      def header(name) = @response[name]
+
+      # How many proofs of work the assistant solved to be answered.
+      def tolls_paid = @response.proofs
+
+      # The proofs of work that pay the toll this refusal demands.
+      def solved_toll = Wire.solve(self['challenges'])
+
+      # The `Link` target with `rel="next"`: the rest of a truncated list.
+      def next_page = header('link').to_s[/<([^>]*)>\s*;\s*rel="next"/, 1]
+
+      def to_s = "#{@response.status} #{@response.body}"
+      alias inspect to_s
+    end
+
+    # Someone's AI assistant at this origin. A demo subclasses it to name what
+    # its customers do there: a shopper orders and pays, a rider reserves and rides.
+    class Customer
+      attr_reader :principal
+
+      # An assistant holding a key and no account at its origin yet.
+      def self.newcomer(assistant)
+        new(assistant, Assistant::Principal.new(agent_id: nil, user_id: nil, token: nil, rsa_key: OpenSSL::PKey::RSA.generate(2048)))
+      end
+
+      def initialize(assistant, principal)
+        @assistant = assistant
+        @principal = principal
+      end
+
+      def origin = @assistant.base_url
+
+      # Pays any proof-of-work toll asked for, unless `unpaid:` or carrying its own `proofs:`.
+      def asks(query, headers: {}, unpaid: false, proofs: nil, **params)
+        headers = headers.merge('Kiosk-PoW' => JSON.generate(proofs)) if proofs
+        Answer.new(@assistant.query(principal, name: query.to_s, headers:, pay_tolls: !(unpaid || proofs), **params))
+      end
+
+      def does(action, headers: {}, **args) = Answer.new(@assistant.run(principal, name: action.to_s, headers:, **args))
+
+      # Signs intent, cart and payment mandates for `total` cents and pays.
+      def pays(total:, scope:, line_items:, currency: 'eur')
+        Answer.new(@assistant.pay(principal, **@assistant.mandates(principal, total:, scope:, line_items:, currency:)))
+      end
+
+      # Signs the `cart` an action answered with, unchanged, and pays.
+      def pays_cart(cart, scope:, currency: cart['currency'])
+        pays(total: cart['total_amount_cents'], scope:, line_items: cart['line_items'], currency:)
+      end
+
+      # The answer says whether a card is on file, or carries the page where the person saves one.
+      def sets_up_payment = does(:payment_setup)
+
+      # Listens for the check's outcome, then asks for it; the answer carries the page
+      # the assistant hands to its person.
+      def requests_verification
+        listens_for(:kyc_verification)
+        does(:request_kyc).tap { @verification = it['request_id'] if it.ok? }
+      end
+
+      # Whether the origin reports the verification this customer asked for last passed.
+      # rubocop:disable-next Naming/PredicateMethod -- public journey DSL name the demo stories call
+      def hears_verification_passed = hears(:kyc_verification, about: @verification)['status'] == 'approved'
+
+      # Hands the origin an identity attestation the person obtained elsewhere.
+      def presents(attestation) = Answer.new(@assistant.kyc(principal, attestation_jws: attestation))
+
+      # What the origin signed into the credential: whose account, in which role.
+      def claims = JWT.decode(principal.token, nil, false).first
+      def account = claims['sub']
+      def role = claims['role']
+
+      def signs_back_in = Answer.new(@assistant.login(principal.rsa_key))
+
+      # This assistant holding the credential a fresh sign-in issues.
+      def with_a_fresh_credential = holding(signs_back_in)
+
+      # Redeems the link code a person handed over; the assistant then acts for that person.
+      def redeems(link_code) = holding(Answer.new(@assistant.claim(link_code, principal.rsa_key)))
+
+      # Asks to be linked to a person's account; the answer carries the code the person approves.
+      def asks_to_be_linked(client_id: 'kiosk-story')
+        Answer.new(@assistant.device_authorization(client_id:, public_key: principal.rsa_key.public_key.to_pem))
+      end
+
+      # Asks once whether the person has approved `request`.
+      def polls(request) = Answer.new(@assistant.device_token(request['device_code'], principal.rsa_key))
+
+      # This assistant holding the credential the person granted through `request`.
+      def collects(request) = holding(polls(request))
+
+      # News the origin publishes on `topic` from now on reaches the assistant.
+      def listens_for(topic)
+        @news ||= @assistant.events(principal)
+        @news.subscribe(topic.to_s)
+      end
+
+      # A connection of its own to the news on `topics`, about `subject`, from after event `since`.
+      def follows(*topics, subject: nil, since: nil)
+        @assistant.events(principal).tap do |news|
+          topics.each { news.subscribe(it.to_s, **{ subject:, since: }.compact) }
+          (@followed ||= []) << news
+        end
+      end
+
+      # What the origin told the assistant on `topic` (about `subject`, carrying `data`),
+      # in the shape the origin publishes for that topic.
+      def hears(topic, about: nil, on: @news, **data)
+        event = on.await { heard?(it, topic, about, data) }
+        errors = Assistant::Events.payload_errors(@assistant.schema, [event])
+        raise Assistant::Events::Error, "#{origin} published #{event} off its schema: #{errors.join('; ')}" if errors.any?
+
+        event['data']
+      end
+
+      private
+
+      def heard?(event, topic, about, data)
+        event['topic'] == topic.to_s && (about.nil? || event['subject'] == about.to_s) &&
+          data.all? { |key, value| event.dig('data', key.to_s) == value }
+      end
+
+      def holding(answer)
+        raise "#{origin} issued no credential: #{answer}" unless answer.ok?
+
+        token = answer['access_token']
+        held  = JWT.decode(token, nil, false).first
+        self.class.new(@assistant, principal.with(agent_id: held['agent_id'], user_id: held['sub'], token:))
+      end
+    end
+  end
+end

data/lib/kiosk/test_helpers/descriptor_examples.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'json_schemer'
+
+module Kiosk
+  module TestHelpers
+    # The examples a served /kiosk/schema publishes, each beside the schema it
+    # must satisfy: `example_params` against `input_schema`, `example_row`
+    # against one row of `output_schema`.
+    module DescriptorExamples
+      PAGING = %w[limit cursor].freeze
+
+      Example = Data.define(:verb, :slot, :value, :schema) do
+        def violation
+          return "#{verb}: #{slot} has no schema to satisfy" unless schema
+
+          errors = JSONSchemer.schema(schema, meta_schema: 'https://json-schema.org/draft/2020-12/schema')
+                              .validate(value).first(3).map { it['error'] }
+          "#{verb}: #{slot} violates its schema — #{errors.join('; ')}" if errors.any?
+        end
+      end
+
+      def self.of(document)
+        (Array(document['queries']) + Array(document['actions'])).flat_map do |descriptor|
+          [params(descriptor), row(descriptor)].compact
+        end
+      end
+
+      def self.params(descriptor)
+        return unless descriptor.key?('example_params')
+
+        declared = descriptor['input_schema']
+        undeclared = PAGING - (declared&.dig('properties')&.keys || [])
+        Example.new(descriptor['name'], 'example_params', descriptor['example_params'].except(*undeclared), declared)
+      end
+
+      def self.row(descriptor)
+        return unless descriptor.key?('example_row')
+
+        declared = descriptor['output_schema']
+        declared = declared.except('type', 'description', 'items').merge(declared['items']) if declared&.dig('type') == 'array' && declared['items'].is_a?(Hash)
+        Example.new(descriptor['name'], 'example_row', descriptor['example_row'], declared)
+      end
+    end
+  end
+end