Order blueprint parameters and methods by name - #308
Merged
Conversation
Sorts request parameters (at every nesting level, since createParameters recurses into object properties) and request methods by name, so the blueprint no longer depends on the order the OpenAPI spec happened to use. That order is incidental today. Body properties reach blueprint as object keys and query parameters as an array, and seam-connect serializes its spec with json-stringify-deterministic, which sorts object keys but cannot sort array elements. So a body-described endpoint arrives alphabetically while a query-described one arrives in declaration order, and an endpoint reorders for no reason other than which representation describes it. This is a pure reordering of existing output: regenerating the seam-blueprint snapshot against the same @seamapi/types 1.1040.0 changes 1846 lines, and every one is a line that also appears on the other side of the diff -- zero lines genuinely added or removed. Verified by comparing the added and removed line multisets. The value is in what it makes reviewable next. Bumping to the semantic-method spec (types 1.1042.0) currently churns 1608/1584 snapshot lines, of which only 46 are real; on top of this commit the same bump is 37/13, which is the real change and nothing else. One test expectation moves with the output: the exempt-endpoint test asserted methods as ['POST', 'PATCH', 'PUT'], the order its fixture inserted the pathItem keys in. It now asserts ['PATCH', 'POST', 'PUT']. The test is about a three-method endpoint being allowed rather than rejected, which it still covers. semanticMethod and preferredMethod are separate explicit fields, so sorting the array loses no information about which method to prefer. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UgJLypfYKgaoAYq7fKy4fs
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Sorts request parameters (at every nesting level —
createParametersrecurses into object properties) and request methods by name, so the blueprint no longer depends on the order the OpenAPI spec happened to use.Why that order is incidental today
Body properties reach blueprint as object keys; query parameters reach it as an array. seam-connect serializes its spec with
json-stringify-deterministic, which sorts object keys but cannot sort array elements. So a body-described endpoint arrives alphabetically and a query-described one arrives in declaration order:Same endpoint, same parameters, different order — purely because of which representation describes it.
This commit changes no content
Regenerating the
seam-blueprintsnapshot against the same@seamapi/types@1.1040.0:Verified by comparing the added and removed line multisets. It is a permutation of existing output, nothing more.
What it makes reviewable
The point is the next PR. Bumping to the semantic-method spec (#306) currently churns the snapshot by 1,608/1,584 lines, of which only 46 are real content. Measured on top of this commit, the same bump becomes:
Same real change, ~97% less noise — the diff becomes the change.
One test expectation moves with the output
createBlueprint: allows more than two methods on exempt endpointsasserted['POST', 'PATCH', 'PUT'], which is the order its fixture inserted the pathItem keys in. It now asserts['PATCH', 'POST', 'PUT'].I changed that expectation because I deliberately changed the output ordering — flagging it rather than burying it. The test is about a three-method endpoint being allowed rather than rejected by the
pathsAllowedMoreThanTwoMethodsguard, which it still covers.semanticMethodandpreferredMethodremain separate explicit fields, so sorting the array loses no information about which method to prefer.Consumer-visible effect
Parameter order in generated docs/SDK output becomes guaranteed alphabetical. 310 of 318 endpoints were already alphabetical (via the object-key sorting described above), so this affects the 8 that were not — those whose parameters came from a
oneOf/allOfbranch flattening, e.g./access_grants/create.Checks
npm test— 78/78 passnpm run typecheck— cleannpm run lint— clean🤖 Generated with Claude Code
https://claude.ai/code/session_01UgJLypfYKgaoAYq7fKy4fs
Generated by Claude Code