keiyaku 0.1.0

data/lib/keiyaku/emitter.rb

@@ -0,0 +1,968 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "json"
+require "rbconfig"
+require_relative "runtime"
+require_relative "names"
+require_relative "emitter/rbs"
+require_relative "emitter/security"
+
+module Keiyaku
+  # Turns an OpenAPI document into three files: value types, a client, and RBS.
+  #
+  # The guiding rule is that anything it cannot translate faithfully becomes a
+  # loud refusal rather than plausible-looking code.
+  class Emitter
+    Refusal = Struct.new(:operation, :reason)
+
+    # One model class to be emitted. `fields` maps the Ruby name to the Ruby
+    # source for its type, `from` to the JSON name where the two differ, and
+    # `open` carries what `additionalProperties` said. Being a value, two of
+    # these built from the same schema compare equal, which is what lets an
+    # inline schema appearing twice be emitted once.
+    Model = Data.define(:fields, :required, :from, :open)
+
+    # Stamped on every file it writes: which generator, and which version of
+    # the runtime contract the code was written against.
+    HEADER = "# Generated by keiyaku #{VERSION}. Edits will be overwritten."
+
+    # Where the runtime is, for the process that reads the generated files
+    # back. Whether it is also an installed gem is not something to depend on.
+    LIB = File.expand_path("..", __dir__)
+
+    SCALARS = {
+      %w[string date-time] => "Time",
+      %w[string date] => "Date",
+      %w[string binary] => "String",
+      %w[string] => "String",
+      %w[integer] => "Integer",
+      %w[number] => "Float",
+      %w[boolean] => ":bool"
+    }.freeze
+
+    attr_reader :refusals, :notes
+
+    def initialize(path, namespace:)
+      @spec = path.end_with?(".json") ? JSON.parse(File.read(path)) : YAML.load_file(path)
+      @namespace = Names.namespace(namespace)
+      @models = {}      # constant name => args for Keiyaku.model(...), or union source
+      @unions = {}      # union source => its RBS expansion, e.g. "Dog | Cat"
+      @deps = {}        # constant name => referenced constant names
+      @poisoned = {}    # constant name => why nothing may be typed as it
+      @refusals = []
+      @notes = []
+      @rbs = RBS.new(namespace: @namespace, models: @models, unions: @unions)
+    end
+
+    # The generated files, and whether Ruby could read them back. Anything
+    # already written stays on disk: reading the file the generator could not
+    # load is how its remaining mistakes get found.
+    attr_reader :broken
+
+    def emit(dir, verify: true)
+      collect_models
+      operations = collect_operations
+      File.write(File.join(dir, "types.rb"), types_source)
+      File.write(File.join(dir, "client.rb"), client_source(operations))
+      File.write(File.join(dir, "#{Keiyaku.snake(@namespace)}.rbs"), @rbs.source(sorted_models, operations))
+      @broken = verify ? load_check(dir) : nil
+      operations
+    end
+
+    # Prose for a generated comment. A refusal quotes the document, and a
+    # document's string can hold a newline: interpolated into a `#` comment it
+    # would end the comment, and whatever came after it would be read as Ruby.
+    # A comment is one line, so this is what a comment can hold.
+    def self.comment(text) = text.to_s.gsub(/\s+/, " ").strip
+
+    private
+
+    # Only the document in hand. A `$ref` into another file is not a narrower
+    # case of this one: taking the last segment of `common.yaml#/Pet` would
+    # name the local Pet, and the client would then load, run, and decode one
+    # schema as another. Bundle the document first; this says so rather than
+    # guessing what was in the file it cannot see.
+    def pointer(ref)
+      raise Impossible, "$ref #{ref.inspect} is not local to this document; bundle it first" unless ref.start_with?("#/")
+
+      ref.delete_prefix("#/").split("/").reduce(@spec) do |doc, key|
+        # ~1 and ~0 are how a JSON Pointer spells / and ~, which a path
+        # template in `#/paths/~1pets/get` is full of.
+        key = key.gsub("~1", "/").gsub("~0", "~")
+        raise Impossible, "$ref #{ref.inspect} does not resolve" unless doc.is_a?(Hash) && doc.key?(key)
+
+        doc[key]
+      end
+    end
+
+    def resolve(node)
+      node.is_a?(Hash) && node["$ref"] ? pointer(node["$ref"]) : node
+    end
+
+    # The constant a `$ref` names, having checked that there is something at
+    # the other end of it and that nothing has spoiled the name.
+    def const_for(ref)
+      pointer(ref)
+      const = Names.constant(ref.split("/").last.gsub("~1", "/").gsub("~0", "~"))
+      raise Impossible, @poisoned[const] if @poisoned.key?(const)
+
+      const
+    end
+
+    # Resolved here rather than in Security, which has no document to look a
+    # $ref up in. An unresolvable one raises where every other bad $ref does,
+    # while the operations are being collected.
+    def security_schemes
+      (@spec.dig("components", "securitySchemes") || {}).transform_values { resolve(_1) }
+    end
+
+    # --- schemas ------------------------------------------------------------
+
+    def collect_models
+      schemas = @spec.dig("components", "schemas") || {}
+
+      # Two schemas wanting one constant is settled before either is built:
+      # whichever came second would otherwise replace the first, and every
+      # operation typed as the first would go on being generated against a
+      # model that is no longer there.
+      names = {}
+      schemas.each_key do |name|
+        const = begin
+          Names.constant(name)
+        rescue Impossible => e
+          # Nothing can refer to it either, so whatever does gets the same
+          # message where it can be acted on: against the operation.
+          next @notes << "schema #{name.inspect} is not emitted: #{e.message}"
+        end
+
+        if (first = names[const])
+          poison(const, "schemas #{first.inspect} and #{name.inspect} both map to #{const}")
+        else
+          names[const] = name
+        end
+      end
+
+      schemas.each do |name, schema|
+        const = names.key(name) or next
+        next if @poisoned.key?(const)
+
+        begin
+          define_model(const, schema)
+        rescue Impossible => e
+          poison(const, "#{const}: #{e.message}")
+        end
+      end
+
+      spread_poison
+    end
+
+    # A component nothing may be typed as. It is a note as well as a poison,
+    # because the operation that gets refused for reaching it is refused two
+    # models further down, and would otherwise be the only thing said about a
+    # schema whose own problem is never mentioned.
+    def poison(const, reason)
+      @notes << reason
+      @poisoned[const] = reason
+    end
+
+    # A model built out of a poisoned one is poisoned too, however far down the
+    # chain it sits, so that no operation is typed as something types.rb does
+    # not go on to define.
+    def spread_poison
+      loop do
+        spread = @deps.filter_map do |const, deps|
+          next if @poisoned.key?(const)
+
+          culprit = deps.find { @poisoned.key?(_1) }
+          [const, "#{const} is built from #{culprit}, which was refused"] if culprit
+        end
+        break if spread.empty?
+
+        @poisoned.merge!(spread.to_h)
+      end
+
+      @poisoned.each_key { @models.delete(_1) }
+    end
+
+    # `upload:` is set while translating a multipart body, where a binary
+    # string means a file rather than a String.
+    def define_model(const, schema, upload: false)
+      schema = merge_all_of(schema)
+
+      # A component that is itself a union is not a model; it is a constant
+      # holding the union, so that a $ref to it still resolves.
+      if schema["oneOf"] || schema["anyOf"]
+        deps = []
+        source = collapse_union(schema, const, deps)
+        expansion = source ? @rbs.type_for(source) : nil
+        source, expansion = union_for(schema, const, deps) unless source
+
+        @models[const] = source
+        @unions[const] = expansion
+        @deps[const] = deps.uniq - [const]
+        return
+      end
+
+      # Nor is a component that is not an object at all. GitHub has ninety-odd
+      # — `author-association` is a string with an enum, `alert-number` an
+      # integer — and a model with no fields casts nothing, so a $ref to one
+      # produced a client that loaded, typechecked, and then raised on the
+      # first response that carried the field. It becomes the type it says it
+      # is, the way the union branch above becomes the union it is.
+      kind = schema["type"]
+      kind = kind - ["null"] if kind.is_a?(Array)
+      unless kind.nil? || Array(kind).include?("object") || schema["properties"]
+        deps = []
+        # An array component and the object inside it are two types, and the
+        # document named only one of them. Hoisting the element under the
+        # component's own name gets `Widgets = [Widgets]`, so the element is
+        # named for being the element.
+        context = Array(kind).include?("array") ? "#{const} item" : const
+        source = type_for(schema, context, deps)
+        @models[const] = source
+        @unions[const] = @rbs.type_for(source)
+        @deps[const] = deps.uniq - [const]
+        return
+      end
+
+      deps = []
+      @models[const] = build_model(const, schema, deps, upload:)
+      @deps[const] = deps.uniq - [const]
+    end
+
+    # Builds the model without deciding what it is called, so that a caller can
+    # compare it against the ones already emitted.
+    def build_model(const, schema, deps, upload: false)
+      declared = schema["required"] || []
+      fields, required, from, seen = {}, [], {}, {}
+      open = open_for(schema, const, deps)
+
+      (schema["properties"] || {}).each do |json_name, property|
+        field = Names.field(json_name)
+        # Keeping the first would leave a model that quietly drops a property
+        # the document declares, and a request body missing a field the caller
+        # thought they had set.
+        if (first = seen[field])
+          raise Impossible, "properties #{first.inspect} and #{json_name.inspect} both become #{field}"
+        end
+
+        seen[field] = json_name
+        fields[field] = type_for(property, "#{const}.#{field}", deps, upload:)
+        required << field if declared.include?(json_name)
+        from[field] = json_name if Keiyaku.camelize(field) != json_name
+      end
+
+      Model.new(fields:, required:, from:, open:)
+    end
+
+    # What `additionalProperties` says about the properties the schema did not
+    # name: nothing, anything, or a type they all have. A document that says
+    # so means it — DIDComm messages carry headers no schema lists, and the
+    # spec has extensions of its own — so the model keeps them rather than
+    # dropping them on the way through.
+    #
+    # Silence stays strict. `additionalProperties` absent is the overwhelming
+    # majority of schemas, plenty of which do mean "and nothing else", and a
+    # model that quietly accepted anything would take a caller's typo along
+    # with it.
+    def open_for(schema, const, deps)
+      case schema["additionalProperties"]
+      when true then "true"
+      when Hash then type_for(schema["additionalProperties"], "#{const}{}", deps)
+      end
+    end
+
+    def merge_all_of(schema)
+      return schema unless schema["allOf"]
+
+      schema["allOf"].map { merge_all_of(resolve(_1)) }.reduce(schema.except("allOf")) do |acc, part|
+        acc.merge(part) do |key, a, b|
+          case key
+          when "properties" then a.merge(b)
+          when "required" then a | b
+          else b
+          end
+        end
+      end
+    end
+
+    # Returns Ruby source for a type, recording model dependencies as it goes.
+    def type_for(schema, context, deps, upload: false)
+      return ":any" if schema.nil? || schema.empty?
+
+      if (ref = schema["$ref"])
+        const = const_for(ref)
+        deps << const
+        return const
+      end
+
+      schema = merge_all_of(schema) if schema["allOf"]
+
+      if schema["oneOf"] || schema["anyOf"]
+        collapsed = collapse_union(schema, context, deps)
+        return collapsed if collapsed
+
+        source, expansion = union_for(schema, context, deps)
+        @unions[source] = expansion unless source == ":any"
+        return source
+      end
+
+      # `type: [string, null]` is 3.1's other way of saying a field may be
+      # null, and means the same as the `anyOf` spelling collapsed above: the
+      # field is a string. More than one type left after dropping null is a
+      # real union with nothing to dispatch on, so it falls through to :any
+      # rather than picking whichever came first.
+      kind = schema["type"]
+      if kind.is_a?(Array) && (rest = kind - ["null"]).size == 1
+        kind = rest.first
+      end
+
+      case kind
+      when "array"
+        # A tuple — `items` as a list in draft-07, `prefixItems` in 2020-12 —
+        # is a fixed-length heterogeneous array, which one element type cannot
+        # describe. Taking the first element's type would be a guess.
+        if schema["items"].is_a?(Array) || schema["prefixItems"]
+          @notes << "#{context}: a tuple, typed as [:any]"
+          return "[:any]"
+        end
+
+        # An array of files is a real multipart shape, so `upload:` carries
+        # into the items — but not into a nested object, where a part is JSON
+        # and a file would be meaningless.
+        "[#{type_for(schema["items"] || {}, "#{context}[]", deps, upload:)}]"
+      when "object", nil
+        # A schema with properties is a model, and stays one when it also
+        # allows properties it did not name: the model carries those. Reading
+        # `additionalProperties` first, as this did, threw the named ones away
+        # and left a bare map in place of the shape the document described.
+        if schema["properties"]
+          hoist(context, schema, deps)
+        elsif (additional = schema["additionalProperties"]).is_a?(Hash)
+          "{ String => #{type_for(additional, "#{context}{}", deps)} }"
+        else
+          ":any"
+        end
+      else
+        format = [kind, schema["format"]].compact
+        if upload && format == %w[string binary]
+          ":upload"
+        else
+          SCALARS[format] || SCALARS[[kind]] || ":any"
+        end
+      end
+    end
+
+    # Two shapes that are unions only on paper. `anyOf: [{type: string},
+    # {type: null}]` is how OpenAPI 3.1 says a field may be null — the field is
+    # a string — and a union whose branches all resolve to one type says
+    # nothing that type does not. Neither is a guess: there is exactly one type
+    # in it. Returns nil when the union is a real one.
+    def collapse_union(schema, context, deps)
+      variants = (schema["oneOf"] || schema["anyOf"]).reject { _1["type"] == "null" }
+      return nil if variants.empty?
+      return type_for(variants.first, context, deps) if variants.size == 1
+
+      # With more than one left, deciding means translating them all, so this
+      # only looks at branches that cannot hoist a model — otherwise comparing
+      # them could leave behind a type nothing goes on to name.
+      return nil unless variants.all? { _1.key?("$ref") || SCALARS.key?([_1["type"]]) }
+
+      scratch = []
+      sources = variants.map { type_for(_1, context, scratch) }
+      return nil unless sources.uniq.size == 1
+
+      deps.concat(scratch)
+      sources.first
+    end
+
+    # A union translates only when the document says how to tell the variants
+    # apart. Casting by trying each one until something sticks is exactly the
+    # plausible-but-wrong behaviour this generator exists to avoid, so an
+    # undiscriminated union stays :any and says why.
+    #
+    # Returns the Ruby source and the RBS that describes it.
+    def union_for(schema, context, deps)
+      keyword = schema["oneOf"] ? "oneOf" : "anyOf"
+      variants = schema[keyword]
+      property = schema.dig("discriminator", "propertyName")
+
+      complaint =
+        if property.nil? then "no discriminator"
+        elsif !variants.all? { _1.key?("$ref") } then "a variant written inline"
+        end
+      if complaint
+        @notes << "#{context}: #{keyword} with #{complaint}, typed as :any"
+        return [":any", "untyped"]
+      end
+
+      consts = variants.map { const_for(_1["$ref"]) }
+      # A mapping's value is either a $ref or the bare name of a schema in
+      # components, which the specification allows and documents use.
+      mapping = (schema["discriminator"]["mapping"] || {}).map do |value, ref|
+        [value, const_for(ref.include?("/") ? ref : "#/components/schemas/#{ref}")]
+      end
+      deps.concat(consts + mapping.map(&:last))
+
+      args = [*consts, "on: #{property.inspect}"]
+      args << "map: { #{mapping.map { |value, const| "#{value.inspect} => #{const}" }.join(", ")} }" if mapping.any?
+      ["Keiyaku::OneOf[#{args.join(", ")}]", (consts + mapping.map(&:last)).uniq.join(" | ")]
+    end
+
+    # An inline object gets its own type rather than degrading to a bare Hash,
+    # named for where it appeared: the body of an operation is that operation's
+    # name, a property is its path down from one. Every such name is a reading
+    # of the document rather than a choice, which is the whole of the rule —
+    # where the document names a type the name is its own, and where it does
+    # not, the position the schema was written in names it.
+    #
+    # Two schemas that are structurally identical are still two types. Matching
+    # them up and keeping the first name would be the generator choosing, and
+    # it chooses badly, because the first name is a record of where it happened
+    # to walk first: it is how a document with 601 inline request bodies got 56
+    # operations sharing a type called after login links, and 25 more sharing
+    # one called after a card mandate.
+    def hoist(context, schema, deps, upload: false)
+      const = Names.constant(context.split(/[.\[\]{}]/).reject(&:empty?).join("_"))
+      own = []
+      model = build_model(const, merge_all_of(schema), own, upload:)
+
+      # The same name asked for twice is not two types. Two schemas written in
+      # different corners of a document can derive one name — an operation
+      # called `pet_error` and a component called `PetError` — and where they
+      # turn out to be the same shape they are one model, since agreeing on a
+      # name they both derived is not the same as being matched up by
+      # structure.
+      #
+      # Where they disagree, typing it :any instead would leave the caller a
+      # Hash where the document describes a shape, and no way to tell which of
+      # the two schemas the name ended up meaning.
+      raise Impossible, @poisoned[const] if @poisoned.key?(const)
+
+      if (existing = @models[const])
+        raise Impossible, "#{const} already names a different schema" unless existing == model
+
+        deps << const
+        return const
+      end
+
+      @models[const] = model
+      @deps[const] = own.uniq - [const]
+      deps << const
+      const
+    end
+
+    # --- operations ---------------------------------------------------------
+
+    def collect_operations
+      @server = choose_server
+
+      @security = Security.new(schemes: security_schemes, default: @spec["security"], notes: @notes)
+
+      operations = (@spec["paths"] || {}).flat_map do |template, path_item|
+        begin
+          path_item = resolve(path_item)
+        rescue Impossible => e
+          # There is no operation to refuse yet — the verbs are on the other
+          # side of the $ref — so the path goes in the report whole.
+          @refusals << Refusal.new(template, e.message)
+          next []
+        end
+
+        path_item.slice("get", "put", "post", "delete", "patch", "head", "options").map do |verb, op|
+          build_operation(verb, template, op, path_item)
+        end
+      end
+
+      # Two operations landing on one name is not a note: whichever the
+      # generator wrote second would take the method, and every call meant for
+      # the other would go somewhere else entirely. Neither is emitted, and the
+      # document has to say which is which.
+      operations.group_by { _1[:name] }.each do |name, group|
+        next if group.size == 1
+
+        reason = "#{group.size} operations map to this name (#{group.map { "#{_1[:verb].upcase} #{_1[:template]}" }.join(", ")})"
+        @refusals << Refusal.new(name, reason)
+        group.each { _1.replace(name:, unsupported: reason) }
+      end
+
+      operations.uniq { _1[:unsupported] ? _1[:name] : _1.object_id }
+    end
+
+    # The one address the generated client is built for. A document may name
+    # several, and this takes the first — but says so, because which of them a
+    # client talks to is not a detail to discover from traffic.
+    #
+    # A URL with variables in it is a URL the document has not finished
+    # writing: `https://{region}.api.test` is not an address, and substituting
+    # a default would be this generator picking a region. It is treated as the
+    # document naming no server at all, which is a case the runtime already
+    # has an answer for.
+    def choose_server
+      servers = @spec["servers"] || []
+      url = servers.dig(0, "url").to_s
+
+      if url.empty?
+        @notes << "no servers declared; a client has to be built with base_url:"
+        return nil
+      end
+      if url.include?("{")
+        @notes << "the server URL #{url} has variables in it; a client has to be built with base_url:"
+        return nil
+      end
+
+      @notes << "#{servers.size} servers declared; #{url} is the one generated" if servers.size > 1
+      url
+    end
+
+    # `servers` on a path item or an operation is an address this client does
+    # not have: the class declares one server, and every method it defines
+    # goes there. Where the client's own is among those declared, that is a
+    # document listing alternatives and the generator picking one of them.
+    # Where it is not, the operation is one whose requests — and whose
+    # credentials — would go somewhere the document did not send them, which
+    # is a refusal rather than a note.
+    def server_problem(op, path_item)
+      declared = (op["servers"] || path_item["servers"] || []).filter_map { _1["url"] }
+      return if declared.empty? || declared.include?(@server)
+
+      "declares its own server (#{declared.join(", ")}), and this client is generated for " \
+        "#{@server || "no server at all"}"
+    end
+
+    # An operationId is optional, and plenty of documents that a server
+    # generates from its own routes carry none, so the verb and the path are
+    # all there is to go on. A path parameter becomes `by_x`, which keeps
+    # GET /pet and GET /pet/{petId} from arriving at the same method.
+    def operation_name(verb, template, op)
+      Names.operation(op["operationId"] || "#{verb}_#{template.gsub(/\{(\w+)\}/) { "by_#{$1}" }}")
+    end
+
+    def build_operation(verb, template, op, path_item)
+      label = op["operationId"] || "#{verb.upcase} #{template}"
+      begin
+        name = operation_name(verb, template, op)
+      rescue Impossible => e
+        # Without a name there is nothing to declare, not even a stub: an
+        # `unsupported :class` would define the method that breaks the client.
+        @refusals << Refusal.new(label, e.message)
+        return { name: nil, label:, unsupported: e.message }
+      end
+
+      translate(verb, template, op, path_item, name)
+    rescue Impossible => e
+      @refusals << Refusal.new(name, e.message)
+      { name:, unsupported: e.message }
+    end
+
+    # What one operation takes: the parameters the path item declared for every
+    # operation under it, and the ones the operation declared for itself. A
+    # parameter is the pair of its name and where it goes, and an operation
+    # naming one the path item already named is narrowing it — a shared `limit`
+    # made required here, or given a smaller maximum — rather than asking for a
+    # second parameter of the same name. Concatenating the two lists would put
+    # it in the client twice, which is a keyword written twice and a file Ruby
+    # will not parse; the duplicate check further down would then report the
+    # document's legal override as the document's mistake.
+    def parameters(op, path_item)
+      declared = ((path_item["parameters"] || []) + (op["parameters"] || [])).map { resolve(_1) }
+
+      # Last wins, and the operation's are last.
+      declared.reverse.uniq { [_1["name"], _1["in"]] }.reverse
+    end
+
+    def translate(verb, template, op, path_item, name)
+      if (problem = server_problem(op, path_item))
+        raise Impossible, problem
+      end
+
+      deps = []
+      params = parameters(op, path_item)
+      query, deep_object, header, exploded, required, types = [], [], {}, [], [], {}
+
+      params.each do |param|
+        style = param["style"] || (param["in"] == "query" ? "form" : "simple")
+        explode = param.fetch("explode", style == "form")
+        types[param["name"]] = type_for(param["schema"] || {}, "#{name}_#{Keiyaku.snake(param["name"])}", deps)
+
+        case param["in"]
+        when "path"
+          raise Impossible, "path parameter #{param["name"]} uses style=#{style}" unless style == "simple"
+
+          # Same style as a header, and the same one thing about it that the
+          # value cannot be asked.
+          exploded << param["name"] if explode
+        when "query"
+          if style == "deepObject"
+            check_deep_object(param)
+            deep_object << param["name"]
+          else
+            raise Impossible, "query parameter #{param["name"]} uses style=#{style}" unless style == "form"
+            raise Impossible, "query parameter #{param["name"]} uses explode=false" unless explode
+          end
+
+          query << param["name"]
+        when "header"
+          header[param["name"]] = Names.parameter(param["name"])
+          # A header is written in `simple` style and nothing else, so the
+          # only thing left to carry is `explode`, which decides how an object
+          # is spelled and cannot be read back off the value at the call.
+          exploded << param["name"] if explode
+        else
+          raise Impossible, "#{param["in"]} parameters are not supported"
+        end
+
+        # A path parameter is positional and required by being one, so this is
+        # only about the keywords. The name is the document's, which is the
+        # one that appears in `query:` and in `header:` both — the Ruby name a
+        # header arrives under is this generator's, and requiredness is not.
+        required << param["name"] if param["required"] && param["in"] != "path"
+      end
+
+      body = form = multipart = content_type = nil
+      # A request body is optional unless the document says otherwise, which is
+      # the specification's default and not this generator's leniency. The
+      # difference is a real one at the call site: POST /user with no body is
+      # a request the server has an answer for, and a client that cannot make
+      # it has to be worked around with a `nil` that goes out as `null`.
+      body_required = false
+      if (request_body = resolve(op["requestBody"]))
+        body_required = request_body["required"] == true
+        content = request_body["content"] || {}
+        binary = content.keys.find { _1 == "application/octet-stream" || content[_1].dig("schema", "format") == "binary" }
+
+        # `+json` is the suffix a vendor media type wears to say its bytes are
+        # JSON, so a body under any of these is one this can build. Where the
+        # document names the plain type as well, that is the one to send: a
+        # server naming both takes both, and the vendor spelling usually
+        # selects a version of the API nobody has asked this client for.
+        jsons = content.keys.select { _1.include?("json") }
+        json = jsons.find { _1 == "application/json" } || jsons.first
+
+        if json
+          body = type_for(content[json]["schema"], "#{name}_body", deps)
+          # Carried only where it is not the plain type, which is what the
+          # runtime sends for a body that says nothing. A server documenting
+          # application/vnd.github+json is entitled to refuse the same bytes
+          # under another name, so the document's own type goes on the wire.
+          content_type = json unless json == "application/json"
+          @notes << "#{name}: request body is sent as #{json}, of #{jsons.join(", ")}" if jsons.size > 1
+        elsif content.key?("application/x-www-form-urlencoded")
+          form = type_for(content["application/x-www-form-urlencoded"]["schema"], "#{name}_body", deps)
+        elsif content.key?("multipart/form-data")
+          multipart = multipart_type(content["multipart/form-data"]["schema"] || {}, "#{name}_body", deps)
+        elsif binary
+          body = ":binary"
+          content_type = binary
+        elsif (text = content.keys.find { _1.start_with?("text/") && text_schema?(content[_1]["schema"]) })
+          # A text body is a String sent as it stands, which is what the
+          # binary case already does; the media type is the only difference,
+          # and the document names it. Where it names several — GitHub's
+          # markdown endpoint takes text/plain and text/x-markdown — the
+          # first is used and the rest are reported, since the schemas differ
+          # only in the header and the caller has no way to say which.
+          @notes << "#{name}: request body is sent as #{text}, of #{content.keys.join(", ")}" if content.size > 1
+          body = ":text"
+          content_type = text
+        else
+          raise Impossible, "request body is #{content.keys.join(", ")}"
+        end
+      end
+
+      # The method's own arguments, which is where two parameter names that
+      # normalise to one show up: Ruby would take `foo-bar` and `foo_bar` as
+      # one keyword written twice, and refuse to parse the file.
+      arguments = template.scan(/\{(\w+)\}/).flatten.map { Names.parameter(_1, positional: true) }
+      arguments << "body" if body || form || multipart
+      arguments += query.map { Names.parameter(_1) } + header.values
+      if (duplicate = arguments.tally.find { |_, count| count > 1 })
+        raise Impossible, "two of its parameters are both called #{duplicate.first}"
+      end
+
+      success, errors = responses(op, name, deps)
+      into = success.empty? ? nil : success
+
+      { name:, verb:, template:, query:, deep_object:, header:, exploded:, required:, types:, body:, form:, multipart:,
+        content_type:, body_required:, into:, errors:,
+        security: @security.source_for(name, op), summary: op["summary"], deps: }
+    end
+
+    # Every success response the document described, by its status. Several of
+    # them are several types, and one method returns one value — but nothing
+    # has to be guessed to reconcile that, because the document says which
+    # type belongs to which status and the response carries the status. GitHub
+    # answers a request for a repository's contributor stats with the stats or
+    # with a 202 meaning it is still counting them; both are the operation's
+    # answer, and casting the second into the first's type is what would need
+    # excusing.
+    def responses(op, name, deps)
+      errors, success = {}, {}
+      seen = { "result" => {}, "error" => {} }
+
+      (op["responses"] || {}).each do |status, response|
+        # `x-` is how an object holds something the specification never gave it
+        # a field for, and the Responses Object is an object like any other.
+        next if status.to_s.start_with?("x-")
+
+        status = status_for(status)
+        content = resolve(response)["content"] || {}
+        json = content.keys.find { _1.include?("json") }
+        schema = json && content[json]["schema"]
+        answered = success_status?(status)
+
+        if schema
+          # Later ones are named for their status, so that two which do not
+          # turn out to be the same shape are told apart. Two which do are the
+          # document repeating itself inside one operation, and the second has
+          # no schema of its own to be named after — which is not the same as
+          # two schemas being matched up by structure and one losing its name.
+          table, kind = answered ? [success, "result"] : [errors, "error"]
+          table[status_key(status)] = seen[kind][schema] ||=
+            type_for(schema, "#{name}#{"_#{status}" if table.any?}_#{kind}", deps)
+        elsif answered && content.any?
+          @notes << "#{name}: #{status} is #{content.keys.join(", ")}, which is returned as the raw body"
+        end
+      end
+
+      # Two statuses that turned out to be the same type are one answer, not a
+      # table to consult at runtime.
+      success = success.first(1).to_h if success.values.uniq.size == 1
+      [success, errors]
+    end
+
+    # What a document may write where a response's status goes: a code, one of
+    # the five ranges the specification allows in place of one, or `default`.
+    # Anything else is not something a response can be matched against, and it
+    # is refused here rather than carried: `4xx` written into the client as it
+    # stands is not Ruby, and a file that will not parse takes down every other
+    # operation in it along with the one that spoiled it.
+    def status_for(status)
+      status = status.to_s
+      return status.upcase if status.match?(/\A[1-5]xx\z/i)
+      return status if status == "default" || status.match?(/\A[1-5]\d\d\z/)
+
+      raise Impossible, "response #{status.inspect} is neither a status code, a range like 4XX, nor default"
+    end
+
+    # A range covering the successes is one of them; `default` is not, being
+    # what the document says about everything it did not describe, and an
+    # operation whose only answer was a catch-all has no type to return.
+    def success_status?(status) = status == "2XX" || status.to_i.between?(200, 299)
+
+    # The key as the generated client writes it. A range is a String — `2XX` is
+    # neither a number nor a name Ruby will take — and the catch-all is the
+    # symbol the runtime looks under once the exact code and the range miss.
+    def status_key(status)
+      return ":default" if status == "default"
+
+      status.match?(/\A\d+\z/) ? status : status.inspect
+    end
+
+    # `deepObject` has exactly one row in the specification's table of styles:
+    # an object, exploded, spelled out a key at a time as filter[status]=live.
+    # The array and primitive columns of that row are written n/a, so an array
+    # under it — which is what Stripe's `expand` is, on 351 parameters — is not
+    # a rendering the specification is quiet about, it is one the specification
+    # says does not exist. Guessing at PHP's `expand[]=` or at `expand[0]=` is
+    # exactly the kind of plausible wrong answer this generator does not give.
+    #
+    # `explode` nominally defaults to false outside `form`, but there is no
+    # unexploded deepObject to default to. A document that leaves it out is
+    # taking the one rendering the style has; a document that writes false is
+    # asking for a second one, and gets told there isn't one.
+    def check_deep_object(param)
+      name = param["name"]
+      raise Impossible, "query parameter #{name} uses style=deepObject with explode=false" if param["explode"] == false
+      return if object_schema?(param["schema"])
+
+      raise Impossible, "query parameter #{name} uses style=deepObject on a schema that is not an object"
+    end
+
+    # `type` is how a document says a schema is an object; `properties` is how
+    # one that left the type out says it anyway.
+    def object_schema?(schema)
+      schema = merge_all_of(resolve(schema || {}))
+      kind = Array(schema["type"]) - ["null"]
+
+      kind == ["object"] || (kind.empty? && schema.key?("properties"))
+    end
+
+    # Whether a text/* body is the string it looks like. A document declaring
+    # an object under text/csv means an encoding this generator does not know,
+    # and passing the model through as the body would send its #to_s.
+    def text_schema?(schema)
+      kind = merge_all_of(resolve(schema || {}))["type"]
+      kind = Array(kind) - ["null"] unless kind.nil?
+      kind.nil? || kind == ["string"]
+    end
+
+    # A multipart body always gets its own type, even where the document points
+    # at a shared component: `format: binary` means a file here and a plain
+    # string everywhere else, and one model cannot mean both.
+    def multipart_type(schema, context, deps)
+      schema = merge_all_of(resolve(schema))
+      return type_for(schema, context, deps) unless schema["properties"]
+
+      hoist(context, schema, deps, upload: true)
+    end
+
+    # --- output -------------------------------------------------------------
+
+    # The generator has no business trusting what it just wrote. A constant
+    # that turned out to be a local variable, a method named for a keyword, a
+    # type referring to a model that never got emitted: none of those are
+    # visible in the document, and all of them are visible the moment Ruby
+    # reads the file back. This is the last place they can be reported against
+    # the document rather than against a stack trace at somebody's first call.
+    #
+    # It runs in another process, because loading the client here would mean
+    # the generator's own namespace, and instantiates it, because a method
+    # named for one the client needs is a file that loads and then recurses.
+    def load_check(dir)
+      script = <<~RUBY
+        require #{File.expand_path(File.join(dir, "client")).inspect}
+        #{@namespace}::Client.new(base_url: "https://keiyaku.invalid")
+      RUBY
+      output = IO.popen([RbConfig.ruby, "-I", LIB, "-e", script], err: %i[child out], &:read)
+      $?.success? ? nil : output.strip
+    end
+
+    def sorted_models
+      ordered, seen = [], {}
+      visit = lambda do |const|
+        return if seen[const]
+
+        seen[const] = :visiting
+        @deps.fetch(const, []).each { |dep| visit.(dep) unless seen[dep] == :visiting }
+        seen[const] = true
+        ordered << const
+      end
+      @models.each_key { visit.(_1) }
+      ordered
+    end
+
+    # The fields go in a Hash of their own rather than as keywords beside
+    # `required:` and `from:`, because they are the API's names and not ours:
+    # a DIDComm message has a property called `from`.
+    # A field that is not an identifier is still a Hash label, in quotes:
+    # `{ "+1": Integer }` is the same Hash as `{ :"+1" => Integer }`.
+    def label(field) = Names.bare?(field) ? field : field.inspect
+
+    # A name that can be written inside `%w[]` or `%i[]`. Neither literal has
+    # any escapes, so the only names they can hold are the ones that need
+    # none: every character here is one that cannot end the list or start an
+    # interpolation. The trailing bang is the runtime's mark for a required
+    # parameter rather than anything the document wrote.
+    LISTABLE = /\A[a-zA-Z0-9_.-]+!?\z/
+
+    # The document's names as source. Written as the word list they read best
+    # as where every name is a word, and one `inspect` at a time where one is
+    # not — a query parameter called `id]` would otherwise close the literal
+    # and leave the rest of its name to be read as Ruby, by the load check
+    # first and by every `require` of the generated client after that.
+    def symbol_list(names)
+      return "%i[#{names.join(" ")}]" if names.all? { _1.match?(LISTABLE) }
+
+      "[#{names.map { _1.to_sym.inspect }.join(", ")}]"
+    end
+
+    def string_list(names)
+      return "%w[#{names.join(" ")}]" if names.all? { _1.match?(LISTABLE) }
+
+      "[#{names.map(&:inspect).join(", ")}]"
+    end
+
+    def model_options(model, defined = [])
+      options = []
+      options << "required: %i[#{model.required.join(" ")}]" if model.required.any?
+      options << "from: { #{model.from.map { |field, json| "#{label(field)}: #{json.inspect}" }.join(", ")} }" if model.from.any?
+      options << "open: #{lazily(model.open, defined)}" if model.open
+      options
+    end
+
+    # A schema that contains itself — a tree with child nodes, two models that
+    # name each other — cannot be written as the constant it is in the middle
+    # of defining. The runtime calls a Proc for the type the first time it
+    # casts one, which is late enough for the constant to exist.
+    def lazily(source, defined)
+      referenced = source.scan(/[A-Z][a-zA-Z0-9]*/).uniq & @models.keys
+      referenced.all? { defined.include?(_1) } ? source : "-> { #{source} }"
+    end
+
+    def types_source
+      defined = []
+      lines = sorted_models.map do |const|
+        model = @models[const]
+        defined << const
+        next "  #{const} = #{model}" if model.is_a?(String)
+
+        fields = model.fields.map { |field, type| "#{label(field)}: #{lazily(type, defined - [const])}" }
+        options = model_options(model, defined - [const]).map { ", #{_1}" }.join
+        one_line = "  #{const} = Keiyaku.model({ #{fields.join(", ")} }#{options})"
+        next one_line if one_line.length <= 110
+
+        "  #{const} = Keiyaku.model({\n    #{fields.join(",\n    ")}\n  }#{options})"
+      end
+
+      <<~RUBY
+        # frozen_string_literal: true
+        #{HEADER}
+
+        require "keiyaku/runtime"
+
+        module #{@namespace}
+        #{lines.join("\n")}
+        end
+      RUBY
+    end
+
+    def client_source(operations)
+      lines = operations.map do |op|
+        next "    # cannot be generated: #{Emitter.comment("#{op[:label]}: #{op[:unsupported]}")}" if op[:name].nil?
+        next "    unsupported :#{op[:name]}, #{op[:unsupported].inspect}" if op[:unsupported]
+
+        args = [":#{op[:name]}", op[:template].inspect]
+        args << "query: #{symbol_list(op[:query])}" if op[:query].any?
+        args << "deep_object: #{string_list(op[:deep_object])}" if op[:deep_object].any?
+        args << "header: { #{op[:header].map { |json, ruby| "#{json.inspect} => :#{ruby}" }.join(", ")} }" if op[:header].any?
+        args << "explode: #{string_list(op[:exploded])}" if op[:exploded].any?
+        args << "required: #{symbol_list(op[:required])}" if op[:required].any?
+        args << "body: #{op[:body]}" if op[:body]
+        args << "form: #{op[:form]}" if op[:form]
+        args << "multipart: #{op[:multipart]}" if op[:multipart]
+        args << "content_type: #{op[:content_type].inspect}" if op[:content_type]
+        args << "body_required: true" if (op[:body] || op[:form] || op[:multipart]) && op[:body_required]
+        args << "into: #{into_source(op[:into])}" if op[:into]
+        args << "errors: { #{op[:errors].map { |status, type| "#{status} => #{type}" }.join(", ")} }" if op[:errors].any?
+        args << "security: #{op[:security]}" if op[:security]
+
+        "    #{op[:verb].ljust(6)} #{args.join(", ")}"
+      end
+
+      <<~RUBY
+        # frozen_string_literal: true
+        #{HEADER}
+
+        require_relative "types"
+
+        module #{@namespace}
+          class Client < Keiyaku::Client
+            server #{@server.inspect}
+        #{@security.table}
+        #{lines.join("\n")}
+          end
+        end
+      RUBY
+    end
+
+
+    # The operation's `into:`. One success response is the type itself; several
+    # are a table for the runtime to read the status against.
+    def into_source(into)
+      return into.values.first if into.size == 1
+
+      "Keiyaku::ByStatus[#{into.map { |status, type| "#{status} => #{type}" }.join(", ")}]"
+    end
+  end
+end