keiyaku 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 03bf89e5b76c37045f10c2b753071967c169d4de12ad428fc778cfbd914db2be
+  data.tar.gz: d191c7f6da38115bdeff90933561694081700d701f18b01b635f4b7a7da2cf07
+SHA512:
+  metadata.gz: 676656c461c9ad9d0866ad9c9ae3eeb1f4d36cfed8853c7270c8dc3372f1503b720760b4b509dc95ff6f38b4dbee9db13a6767275f79af98176a8bd807bcc07b
+  data.tar.gz: 6fa784f8019ccce7a772cb2ea7d2dff1371b3159782ce4820274f7cb712195f6ed4f48ea10874d1f86b26e516714f1dbb4c1a5101c87a12a7286fd0bb7ba3632

data/CHANGELOG.md

@@ -0,0 +1,149 @@
+# Changelog
+
+## 0.1.0 — 2026-07-28
+
+First cut. Generates a client, its value types and an RBS file from an OpenAPI
+3.0 or 3.1 document.
+
+- `Keiyaku::Client` DSL: one line per operation, real method arity
+- `Keiyaku.model`: schemas as `Keiyaku::Model` subclasses — frozen, compared by
+  value, copied with `#with`, pattern-matched. Casting a response ignores
+  fields the document never mentioned; constructing one refuses a keyword it
+  does not know, which is a typo rather than a server that has moved on
+- `additionalProperties` is carried rather than dropped: a schema that says
+  there may be properties it did not name gets a model that keeps them, read
+  through the same `[]` as a property Ruby will not take through a dot, and
+  written back under the names they arrived with. A schema that says nothing
+  stays as strict as it was
+- `style`/`explode` defaults (`form` for query, `simple` for path and header)
+- `style: deepObject` query parameters, which go out as `filter[status]=live`.
+  The style has one rendering in the specification and it is an object's, so
+  that is what is generated: an array under `deepObject`, which is what Stripe
+  writes on `expand`, is refused rather than guessed at, and so is a value
+  nested a level deeper than the specification describes
+- security is compiled per operation, from the operation's own requirement or
+  the document's: alternatives, schemes required together, and `security: []`.
+  Credentials are given by scheme name, and a scheme nothing can send refuses
+  only the operations that require it
+- API key in a header, query parameter or cookie; bearer and basic; OAuth 2
+  and OpenID Connect access tokens, which are bearer tokens
+- typed error bodies, mapped to `Keiyaku::ClientError` / `ServerError`; a
+  request that never happened is a `Keiyaku::ConnectionError` whichever adapter
+  it was, with the transport's own exception on `#cause`
+- `timeout:` takes `{ open:, read: }` as well as one number for both
+- constructs that cannot be translated faithfully are refused at generation
+  time and raise `Keiyaku::Unsupported` if called
+- inline schemas are named for where the document wrote them — the operation
+  for a body or a response, the path down for a nested property — and two that
+  are structurally identical stay two types, since the name a structural match
+  keeps records where the generator walked rather than what the document says
+- `oneOf`/`anyOf` with a `discriminator` becomes a `Keiyaku::OneOf`, including
+  the document's `mapping`; without one it stays `:any` and says so
+- `multipart/form-data` request bodies, with `Keiyaku::Upload` for file parts
+- optional adapters for faraday and http.rb, required explicitly rather than
+  depended on
+- response header names are lower-cased before use, so an adapter that returns
+  them any other way still decodes
+- retry backoff has jitter
+- `Keiyaku.model` takes its fields as a positional Hash, so a property named
+  `from` or `required` cannot displace the option of the same name
+- `anyOf` of a type and `null`, or of branches that all agree, keeps the type
+  instead of degrading to `:any`
+- operations with no `operationId` are named for their verb and path; two that
+  would land on one name are both refused
+- a document with no `servers` is a note, and building such a client without
+  `base_url:` raises rather than failing later inside `URI`
+- a tuple (`items` as a list, or `prefixItems`) no longer crashes the generator
+- every Ruby name goes through one table, which refuses what Ruby will not
+  take: a schema whose name is not a constant, an `operationId` that is a
+  keyword, two schemas or two parameters or two properties that normalise onto
+  one name
+- several success responses have to agree on a type, or the operation is
+  refused rather than casting one status's body into another's model
+- `$ref` is resolved with JSON Pointer escaping and only within the document:
+  one into another file is refused rather than silently naming a local schema
+  that happens to end in the same segment
+- a schema that contains itself is typed lazily instead of referring to a
+  constant in the middle of its own definition
+- the generator loads what it wrote, in another process, and reports a file
+  Ruby cannot read back as a bug in itself rather than leaving it to be found
+  at the first `require`
+- a name the document chose reaches the generated files as data rather than as
+  text spliced into them. A query parameter called `id]` used to close the
+  `%i[]` it was written in and leave the rest of its own name to be read as
+  Ruby — by the load check first, since that runs what it just wrote, and by
+  every `require` of the client after it. The same for `deepObject` names and
+  for the refusals written as comments, which are now kept to the one line a
+  comment holds
+- `--module` has to be one Ruby constant, said against the flag rather than
+  found later in a file that will not load
+- which query and header parameters are required is declared once, as
+  `required: %i[status]`, rather than marked with a bang on the end of each
+  name. A document may name a parameter `notify!` itself, and the mark made
+  that one required and sent it as `notify`
+- a response keyed by a range — `4XX`, which is how a document describes its
+  client errors in one go — is matched as one instead of read as the number 4.
+  It used to be written into the client unquoted, which is not Ruby: the file
+  did not parse, so every other operation in it was lost along with the one
+  that carried the range. The runtime reads the exact code first, then the
+  range that covers it, then `default`. A status that is none of the three is
+  refused, which costs the one operation rather than the file
+- an operation's second error response is named for its status where the shapes
+  disagree, the way a second success response already was. Two errors of one
+  shape are still one type; two of different shapes used to refuse the
+  operation over the name they both derived
+- a request body is optional unless the document required it, which is the
+  specification's default and so is the DSL's: `body_required: true` is written
+  down and its absence is the document's silence, rather than the other way
+  round. It used to be a positional argument either way, so an endpoint that
+  takes an empty body could only be called with a `nil` that went out as `null`
+  under a Content-Type. Left out now it is no body at all
+- a request body under a vendor media type keeps it: `application/vnd.acme+json`
+  is built as the JSON its `+json` says it is, and sent under the name the
+  document gave rather than relabelled `application/json`, which a server
+  documenting the one is entitled to refuse. Where a document declares both,
+  the plain type is taken and the choice is a note
+- a parameter an operation declares again is the document narrowing the path
+  item's — required here, optional elsewhere — rather than two parameters of
+  one name. It used to be both, which is one Ruby keyword written twice, and
+  the operation was refused for a duplicate the document never wrote
+- `servers` on a path item or an operation is answered rather than ignored: it
+  is refused unless the client's own server is among the ones it lists, since
+  generating it would send that operation, and its credentials, to a host the
+  document did not name. Several at the top level is a note saying which was
+  taken, and a URL with variables in it is treated as no address at all rather
+  than sent to a host called `{region}`
+- an error body is cast to whatever type the document declared for that status
+  rather than only to the ones that are a model. An error described as a list
+  of problems arrives as that list; one described as a map was calling
+  `Hash#cast`, and one the document left without a shape was calling
+  `Symbol#cast` — a `NoMethodError` in place of the error the server sent,
+  taking the status and the body with it, and matching no `rescue` the caller
+  could have written. A body that does not fit the type it was declared with
+  is kept as it arrived, since what answers a 502 is usually written by a
+  proxy that never read the document
+- a path or header parameter that is not a scalar goes out in the `simple`
+  style the specification gives it: `1,2` for a list, and `role,admin` — or
+  `role=admin` where the document wrote `explode`, which the operation now
+  carries — for an object. It used to be whatever `#to_s` made of the value,
+  so a list reached the server as a string with brackets and a space in it and
+  an object as a Ruby Hash literal, neither of which anything reads back
+- a request with no body reaches the server without a Content-Type on every
+  net/http there is. Net::HTTP gives a POST that was handed none an empty body
+  of its own, and net/http before 0.5 labels that empty body
+  `application/x-www-form-urlencoded` — so an optional body left out went out
+  under a media type this client never chose, on the Rubies whose standard
+  library is that old. The adapter says there is no body rather than leaving
+  one to be invented, and sends the length as the zero it is
+- a path parameter is percent-encoded the way RFC 6570 says its style is: down
+  to the unreserved characters, and inside the separators rather than over
+  them. The whole segment used to go through `URI.encode_www_form_component`,
+  which is the query's encoding and not a path's — a space became `+`, which
+  in a path is a plus sign, and the comma between two elements of a list was
+  encoded along with any comma inside one, so that neither could be told from
+  the other at the far end
+- `Retry-After` is read in both the forms RFC 7231 writes it: the seconds to
+  wait, and the date the wait is over. The date raised an `ArgumentError` from
+  the middle of the retry — out of the call the header was asking to have made
+  again — and one already past now means go now rather than a negative sleep.
+  A header in neither form is no instruction and leaves the wait to the backoff

data/DESIGN.md

@@ -0,0 +1,418 @@
+# Design notes
+
+Why keiyaku is shaped the way it is, and what it does with the parts of
+OpenAPI that are not obvious. [README.md](README.md) is the shorter way in.
+
+## How it splits
+
+Generated code carries only what is specific to one API: the operation table
+and the schema fields. Everything else lives in `lib/keiyaku/runtime.rb` —
+transport, auth, the `style`/`explode` parameter rules, body encoding, response
+casting, error mapping, retries. The contract between the two is one method,
+`Client#__invoke`, so the runtime can change without regenerating anything.
+
+Terseness in `client.rb` costs nothing in tooling because the emitted RBS
+carries the full signature:
+
+```rbs
+def find_pets_by_status: (status: String) -> Array[Pet]
+def update_pet_with_form: (Integer pet_id, ?name: String?, ?status: String?) -> Pet
+def get_inventory: () -> Hash[String, Integer]
+```
+
+The gem ships `sig/keiyaku.rbs` for the runtime itself, so a generated
+`class Client < Keiyaku::Client` resolves rather than dangling. `rake rbs`
+validates the examples against it, which is the check that would have caught
+the generated RBS being subtly unresolvable.
+
+That the signatures resolve is not yet that they are true. `rake steep` reads
+[`checks/`](checks) — calling code for each example, which never runs — against
+the RBS emitted beside that example, so a signature that has drifted from the
+client it describes fails the build rather than somebody's editor.
+[`checks/rejected.rb`](checks/rejected.rb) asks it from the other side: every
+line there is wrong on purpose and names the complaint it has to draw, because
+correct usage cannot tell a signature that is right from one that has quietly
+gone `untyped` — both accept it. Steep reports an ignore comment it did not
+need, so the day a type stops constraining what it says it constrains, the
+assertion that it does goes redundant and the run fails.
+
+The DSL builds real methods with real arity — `get :get_pet_by_id,
+"/pet/{petId}"` defines `get_pet_by_id(pet_id)`, and calling it wrong raises
+`ArgumentError` at the call, not a confusing failure inside the client.
+`required:` says which query and header parameters a caller has to pass, by
+the name the document gave them: `query: %i[status limit], required: %i[status]`.
+It is said in one place rather than marked on each name, because a name is the
+document's — one called `notify!` is a parameter called `notify!`, not an
+optional one wearing the mark for a required one.
+
+## Why the model fields sit in a Hash
+
+```ruby
+Pet = Keiyaku.model({
+  id: Integer, name: String, category: Category, photo_urls: [String],
+  tags: [Tag], status: String
+}, required: %i[name photo_urls])
+```
+
+The fields sit in a Hash of their own rather than as keywords beside
+`required:`, because they are the API's names and not ours. A DIDComm message
+has a property called `from`, which as a keyword would quietly have taken the
+place of the option that maps JSON names.
+
+## Unions and uploads
+
+A `oneOf` carrying a `discriminator` becomes a union that dispatches on it:
+
+```ruby
+Event = Keiyaku::OneOf[WidgetCreated, WidgetRetired, on: "kind",
+                       map: { "created" => WidgetCreated, "retired" => WidgetRetired }]
+```
+
+and the RBS gets `type event = WidgetCreated | WidgetRetired`. Without a
+discriminator there is nothing to dispatch on, so it stays `:any` and the run
+says so — casting by trying each variant until one sticks would be a guess.
+
+Some unions are only unions on paper, and those keep their type. `anyOf: [{type:
+string}, {type: null}]` is how OpenAPI 3.1 says a field may be null, and a union
+whose branches all resolve to the same type says nothing that type does not:
+both become `String`. Neither is a guess, so neither is worth a note.
+
+An `enum` is read as the type it restricts and nothing more: `{type: string,
+enum: [available, pending, sold]}` is a `String`, in the model and in the RBS
+alike. The values are not carried, not checked when a response is cast, and not
+checked when a request goes out — a value the document does not list is a call
+the client makes happily.
+
+This is a gap rather than a decision about what the list means. Two things are
+worth knowing about closing it. The values belong in the signature, where RBS
+has literal types and `status: "avaliable"` can be a typo the typechecker
+catches, and not in the cast, where enforcing them would break a working client
+on a server adding a value — which OpenAPI permits and APIs do. And an `enum`
+in JSON Schema is a list of values, not a list of strings: objects, arrays and
+mixed types are all legal in one, and none of those has a literal to be written
+as, so any version of this describes some lists and leaves the rest as the type
+they already are.
+
+A schema that says `additionalProperties` is a document telling you there will
+be properties it did not name, and the model keeps them. DIDComm is the case in
+hand: the specification has header extensions of its own and an implementation
+may add more, so a client that dropped them could not forward a message it had
+not composed itself.
+
+```ruby
+Message = Keiyaku.model({ id: String, body: { String => :any } },
+                        required: %i[id], open: true)
+
+message = Message.cast(wire)
+message.id                             # a declared property, through a dot
+message["please_ack"]                  # one the schema never named
+message.to_json_hash == wire           # true — nothing was dropped on the way
+```
+
+They are read through the same `[]` that reads a property whose name Ruby will
+not take through a dot, so an open model has no API a closed one lacks. They
+stay out of `members`, `to_h` and pattern matching, which describe the shape
+the document actually specified. Their keys keep the spelling they arrived
+with — a declared property has the document's name to map back to and an
+undeclared one has nothing, so camelizing it would be a guess, and that is
+what makes the round trip lossless.
+
+`additionalProperties: {type: integer}` says what the values are, and the model
+casts them. A schema that says nothing stays strict: absent is the great
+majority of schemas, plenty of which do mean "and nothing else", and a model
+that quietly accepted anything would accept a caller's typo along with it.
+
+A `multipart/form-data` body is a model like any other, except that a property
+with `format: binary` is typed `:upload`:
+
+```ruby
+post :upload_photo, "/widgets/{id}/photo", multipart: UploadPhotoBody, into: Widget
+
+client.upload_photo(1, Widgets::UploadPhotoBody.new(
+  file: File.open("kaya.png"), caption: "a dog", tags: %w[dog good]
+))
+```
+
+A bare IO is wrapped in a `Keiyaku::Upload`, taking its filename from the path;
+construct one yourself to set the filename or content type. An array property
+becomes one part per element.
+
+A body the document describes as text goes out as it stands, under the media
+type the document named, and so does a binary one — neither is JSON, and the
+only thing the generator has to know is what to put in the header.
+
+An operation whose statuses are different types is all of them. GitHub answers
+a request for a repository's contributor stats with the stats, or with a 202
+meaning it is still counting; the document says which type belongs to which
+status and the response carries the status, so nothing has to be guessed:
+
+```ruby
+post :import_widgets, "/widgets/import", body: :text, content_type: "text/csv",
+     into: Keiyaku::ByStatus[200 => [Widget], 202 => ImportQueued]
+```
+
+and the RBS returns `(Array[Widget] | ImportQueued)`, which is a caller that
+has to look. A status the document did not describe is passed through undecoded
+rather than cast into a type the server never claimed to be sending.
+
+## Transport
+
+The default is `net/http`, and the gem has no dependencies. An adapter is one
+method:
+
+```ruby
+def call(verb, uri, headers, body) = [status, headers, body]
+```
+
+Each lives in a file of its own, the stdlib one included: the runtime holds the
+seam and none of the transport, and `keiyaku/adapters/net_http` is autoloaded by
+the client that was given no adapter, so an application on another stack never
+loads `net/http` at all.
+
+Two more are shipped without being loaded, or depended on:
+
+```ruby
+require "keiyaku/adapters/faraday"
+
+client = Petstore::Client.new(adapter: Keiyaku::FaradayAdapter.new(connection))
+```
+
+`keiyaku/adapters/http` is the same for http.rb. Neither gem is a dependency
+and neither will become one: a client for one API has no business choosing an
+HTTP stack for the application around it. Response header names come back in
+whatever case the library uses; the runtime lower-cases them, so an adapter
+cannot get that wrong. Built-in retries back off exponentially with jitter and
+honour `Retry-After`; if Faraday is already carrying faraday-retry, build the
+client with `retries: 0` and let the middleware do it properly.
+
+A request that never happened — connection refused, DNS failure, a timeout —
+is a `Keiyaku::ConnectionError` whatever is underneath, with the library's own
+exception on `#cause`. Otherwise the seam leaks: an application that moved a
+client from `net/http` to Faraday would find its `rescue` matching nothing, and
+a refused connection taking the process down.
+
+`timeout:` is one number for both phases or two:
+
+```ruby
+Petstore::Client.new(timeout: { open: 2, read: 10 })
+```
+
+Waiting to find out a host is not there and waiting for a slow answer are two
+different patiences, and a client that sits mid-request inside somebody else's
+application has to bound the first much more tightly than the second.
+
+## Refusing rather than guessing
+
+The failure mode that matters is a generator emitting plausible code that is
+subtly wrong. When this one cannot translate a construct faithfully it says so
+at generation time and emits an operation that raises:
+
+```
+8/9 operations, 3 files
+
+refused to generate 1 operation(s):
+  - list_widgets: query parameter expand uses style=deepObject on a schema that is not an object
+
+Calling one raises Keiyaku::Unsupported. Write those by hand.
+```
+
+What it refuses is anything where the generated code would be a guess: a name
+Ruby will not take or that two things want at once, a `$ref` into a file it
+cannot see, a body in an encoding it does not know, a security scheme it has
+no way to send. Then, because the mistakes it does not know to look for
+are still in the file it wrote, it reads that file back in another process and
+reports what will not load as a bug in itself.
+
+`servers` is the same judgement about an address. The client declares one and
+every method it defines goes there, so a path item or an operation that names
+a server of its own is refused unless the client's is among the ones it lists
+— generating it anyway would send that operation's requests, and the
+credentials on them, to a host the document did not name. Where the document
+declares several at the top level the first is generated and the note says so,
+and a URL with variables in it (`https://{region}.api.test`) is treated as no
+address at all, since substituting a default would be the generator picking a
+region.
+
+The line it draws is the specification's, not a shortlist of what has been
+implemented. `deepObject` is the clearest case. Its one row in OpenAPI's table
+of styles is an object, exploded, and that is generated:
+
+```ruby
+client.search_widgets(q: "kaya", filter: Widgets::SearchWidgetsFilter.new(status: "live"))
+# GET /widgets/search?q=kaya&filter[status]=live
+```
+
+The array and primitive columns of that row are written n/a, so an array under
+`deepObject` — which is what Stripe writes on `expand`, on 351 parameters — is
+not something the specification is quiet about, it is something the
+specification says has no spelling. `expand[]=a` and `expand[0]=a` are both
+plausible and neither is described, so that one is refused. Stripe's document
+generates 352 of its 619 operations, and every one of the 267 it does not is
+held up by exactly this.
+
+## Credentials
+
+An operation is authenticated the way the document says that operation is
+authenticated — which is not always the way the one above it is. The Petstore
+declares two schemes and uses them differently across nineteen operations, so
+credentials arrive by the name the document gave the scheme:
+
+```ruby
+client = Petstore::Client.new(auth: { api_key: ENV["PETSTORE_KEY"] })
+
+client.get_inventory          # api_key: ...
+client.get_pet_by_id(5)       # api_key: ..., the first of two alternatives
+client.add_pet(pet)           # raises: this one documents petstore_auth
+```
+
+A single value is allowed where the document declares one scheme, since naming
+it would be ceremony. With two it is refused, because assigning it to whichever
+came first is exactly how a client ends up sending an API key to the endpoints
+that document OAuth. A client built with no credentials at all is taken at its
+word and sends none: plenty of servers do not enforce what their document
+declares, and that is not this library's call to make.
+
+## Documents nobody wrote by hand
+
+A document a server produced from its own routes tends to be missing the things
+a hand-written one has, and the generator has to cope rather than refuse.
+[`examples/sidecar-inline.json`](examples/sidecar-inline.json) is one, checked in
+exactly as the service printed it — ten routes, and every one of these true at
+once:
+
+- **No `operationId`.** The verb and the path are then all there is to name a
+  method with, so `POST /didcomm/pack/encrypted` becomes
+  `post_didcomm_pack_encrypted` and a path parameter becomes `by_id`, which
+  keeps `GET /things` and `GET /things/{id}` apart. Two operations that would
+  still land on one name are both refused, since whichever was written second
+  would take the method and every call meant for the other would go to a route
+  it does not name.
+- **No `components`.** Every schema is then written out again under each
+  operation, and each copy becomes its own model named after the operation it
+  was written under. Ten routes over four shapes is seventy-one types rather
+  than the thirty-one that matching them up by structure would give, and the
+  forty extra are the price of never having chosen a name — see below.
+- **No `servers`.** The address has to come from the application, so that is a
+  note at generation time and a `Keiyaku::Error` naming the client if one is
+  built without `base_url:`.
+
+A document like this is worth more as a test than one written for the purpose,
+because it was not written for the purpose. Every defect found in the generator
+so far came from pointing it at that file rather than at the two hand-written
+ones.
+
+### What naming them is worth
+
+[`examples/sidecar.json`](examples/sidecar.json) is the same service after it
+gave its eight shared shapes a `$id`, and nothing else about it changed: same ten
+routes, still no `operationId`, still no `servers`, still printed rather than
+written. So the pair is the one place here that isolates what a name does.
+
+| | inline | named |
+| --- | --- | --- |
+| models | 71 | **32** |
+| `types.rb` | 434 lines | **179 lines** |
+| RBS | 686 lines | **302 lines** |
+| notes | 13 | **4** |
+
+The forty-odd models that go are the copies. A DIDComm message is one type
+instead of four, so a caller can build a message and pack it encrypted, signed
+and plaintext — with four types there was no value that more than one of the
+three would take. The notes drop the same way: `Attachment.data` is an `anyOf`
+with nothing to dispatch on once rather than four times.
+
+It also settles a case the generator cannot settle itself. `POST /did/resolve`
+answers 200 and 400 with the same shape, and in the inline document those are two
+schemas that merely look alike, so they stay two types — matching them up would
+hand a caller rescuing the error a type whose name said the call had succeeded.
+In the named document both say `DIDResolutionResult`, which is the document
+stating that they are one type, and the generator agrees because it was told
+rather than because it guessed. Both examples pin their own side of that.
+
+## Where the names come from
+
+Every type is named by reading the document, and the generator never picks
+between two names that both fit. Where the document names a type — anything in
+`components/schemas` — the name is its own. Where it does not, the position the
+schema was written in names it: an operation's request body is that operation
+plus `Body`, a success response plus `Result`, an error plus `Error`, and a
+property nested inside one of those is its path down from it.
+
+Two schemas that happen to be structurally identical are still two types. This
+is the rule that costs the most — Stripe writes out all 601 of its request
+bodies inline, and matching them up drops 5,014 models to 2,306 — and it is
+still the right way round, because the name a structural match keeps is a
+record of where the generator walked first rather than of anything in the
+document. That is how 56 unrelated Stripe operations came to share a body type
+called `PostAccountsAccountLoginLinksBody`, 25 more a type called after a card
+mandate, and how the inline sidecar's `POST /did/resolve` came to declare its own
+success type as its 400 body — a caller rescuing the error got a value whose
+class said the call had succeeded.
+
+The one thing that is still shared is a name derived twice. An operation's 400
+and its 404 are both `#{name}Error`, and where the document gives them the same
+shape they are one model; where it does not, the second is named for its status
+— `#{name}404Error` — the way a second success response already was. Two names
+derived from one document are not the same thing as two schemas matched up by
+structure, which is what the rule above is about.
+
+## Tests
+
+`rake` regenerates the examples, validates their RBS, type-checks calling code
+against it, and runs the specs — 247 RSpec examples covering name mapping in
+both directions, nested and array models, pattern matching, query array
+explosion, header parameters overriding credentials, per-operation security,
+typed error bodies, binary, text, vendor JSON and multipart request bodies,
+discriminated unions, responses cast by their status and by the range their
+status falls in, and cast errors naming the offending field.
+
+Nothing is stubbed. The generated clients talk to a real HTTP server on a real
+socket ([`spec/support/test_server.rb`](spec/support/test_server.rb)), which
+also records what it was sent, so an example can assert on the request as well
+as the response. A stubbed adapter would only agree with whatever the runtime
+happened to do. The examples run in random order and each one starts with no
+outstanding requests, so none of them depends on another having run first.
+
+A second document, [`examples/widgets.yaml`](examples/widgets.yaml), exists to
+keep the generator honest about not being fitted to the Petstore: OAS 3.1,
+bearer auth, a `default` error response, and JSON fields that are already
+snake_case (which the camelCase convention would otherwise guess wrong). Its
+`POST /widgets/import` holds the three things a document is entitled to say
+and Ruby is awkward about — a text body, a parameter called `until`, and two
+success statuses that are two types — because each of them was a refusal until
+GitHub's document turned one up. `POST /widgets/{id}/notes` holds three more
+that were wrong rather than refused: a body under the server's own `+json`
+media type, a body the document never required, and errors described as `4XX`
+rather than one code at a time. It also carries both sides of the `deepObject`
+line at once: `GET /widgets/search` takes one on an object and is generated,
+`GET /widgets` takes one on an array and is the document's single refusal.
+
+The third and fourth were not written for this at all — see above — and are two
+prints of one service, before and after it named its shared shapes. Both clients
+are generated and both RBS files validated on every run like the others.
+[`spec/sidecar_inline_spec.rb`](spec/sidecar_inline_spec.rb) asserts that every
+type in [`examples/sidecar-inline.json`](examples/sidecar-inline.json) is named
+after the operation it was written under, which is the whole of the naming rule
+on a document that names nothing itself;
+[`spec/sidecar_spec.rb`](spec/sidecar_spec.rb) asserts that
+[`examples/sidecar.json`](examples/sidecar.json) takes the eight names the
+document does give, that the operations sharing a shape share a type, and that
+what the document still leaves inline is still named by position.
+
+The inline copy is frozen on purpose. It does not track the service and is not
+refreshed from it — what it holds is not the sidecar but the shape of a document
+with no `components` at all, which is a thing servers emit and which nothing else
+here exercises.
+
+The optional adapters are covered by the same suite, over the same socket, when
+faraday and http.rb happen to be installed. They are marked pending otherwise,
+since neither is a dependency.
+
+Saying they are optional is worth nothing unless something checks it, so CI
+runs the suite a second time against
+[`gemfiles/bare.gemfile`](gemfiles/bare.gemfile), which carries neither gem: a
+stray `require` in the runtime fails there rather than on somebody's first
+install. A third job builds the gem, installs it into an empty prefix, and
+generates a client from outside the checkout — nothing from the working tree is
+on the load path, which is what catches a file the gemspec forgot to list. The
+matrix runs 3.2, the floor `Data.define` puts the gemspec at, through 4.0.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 merely
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.