Repository navigation
fix(compilers/openapi)!: record $self on the document's source - #732
Open
fuad-daoud wants to merge 7 commits into
Open
fuad-daoud wants to merge 7 commits into
fuad-daoud wants to merge 7 commits into
Conversation
ir.SourceInfo gains SelfURI, the URI a document declares for itself, and the OpenAPI compiler fills it from doc.GetSelf(). It sits on the source entry rather than on the Document because it is a fact about one input file: several may be loaded, each may declare its own, and a document-level field could not say which file declared it. The URI is recorded at every supported minor, not gated to 3.2. The library parses `$self` at every 3.x minor and reports no finding for it, so a version gate would drop a declared value without reporting it — the defect this closes. An empty `$self` and an unset one are one state and one field value: an empty URI reference is not a base URI (RFC 3986 §5.1), so it identifies nothing when documents are combined. Out of scope, stated in the field's GoDoc: resolving relative references through the URI (GitHub #74 owns that wiring), and reporting a `$self` written by a dialect that does not define it. The field raises no diagnostic of its own. IRVersion stays 0.6.0: a new optional member is none of the shape changes docs/ir-design.md §2.1 moves the version for.
Plans and agent working notes are not part of the repository; what a reviewer needs is in the PR body, the commits and the linked issues. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
SourceInfo.SelfURI's doc comment was 144 words and assertSelfURI's 109, so TestDocComments_StayUnderTheCap failed the gate. Both keep their reasoning in fewer words.
The fixture predates the idSpaces declaration main introduced with IR 0.7.0. Only irVersion and idSpaces change.
SourceInfo gained selfURI. ir-design §2.1 moves the version on any change to a Document's JSON shape, and a decoder pinned to 0.7.0 refuses the new member, so a document carrying it is unreadable there. BREAKING CHANGE: documents are stamped irVersion 0.8.0; consumers built against 0.7.0 refuse them.
This was referenced Oct 13, 2026
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
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.
Summary
ir.SourceInfogainsSelfURI(json:"selfURI,omitempty"), and the OpenAPI compiler fills it fromdoc.GetSelf(). It sits on the source entry besideformat,pathandhashbecause$selfis a fact about one input file, not about the document: several may be loaded, each may declare its own, and a document-level field could not say which file declared it.$selfis the case that would have been dropped; the recorded value is the declared one either way.$self: ""and an unset$selfare one state: an empty URI reference is not a base URI (RFC 3986 §5.1), it identifies nothing when documents are combined, and nothing downstream can act on the difference. That is why the field is a plainstringwithomitempty.$selfwritten by a dialect that does not define it — the analogous location check forallowReservedis openapi: allowReserved on a path or header parameter is kept without a warning #628, not this change. This change adds no diagnostic code.openapi.Options,pass/,engine/, CLI orirverifychange.IRVersionstays0.6.0.docs/ir-design.md§2.1 moves the version for "a key renamed or removed, an encoding changed, or the meaning of an existing key changed"; a new optional member is none of those, and the one pure field addition in the history (Property.Constraints,ecd2e78) landed without one. Counter-reading, stated not hidden:ir/document.gowarns that a shape change reaching main without a bump leaves a consumer pinned to the old version accepting a document it cannot read, and a 0.6.0 build handed a document carryingselfURIdoes fail to decode it — loudly, on the unknown member. This PR takes the §2.1 enumeration. If the batch owner rules the other way, the follow-up is mechanical and touches nothing else here: bump the constant to0.7.0with a log paragraph, re-anchorTestCompatibleVersion's three neighbour literals, run the-updatesweep, and title the PRfeat(ir)!: ….Test plan
go test ./ir -run TestSourceInfo— the wire shape: a declared URI underselfURIbyte-exact besideformat/path/hash, and no key at all when unset; each row also decoded back.go test ./compilers/openapi -run TestParse_RecordsSelfURI— five rows: 3.2 with$self, 3.2 without, 3.2 with$self: "", 3.1 with, 3.0 without; each asserting no error diagnostic, one source, andSources[0].SelfURI.testdata/conformance/openapi/self-uri.yaml(3.2.0,$self,info,paths: {}) with{"self-uri", assertSelfURI, nil}and its golden;go test ./compilers/openapigreen,unwitnessed.golden.txtunchanged.SelfURI: doc.GetSelf()reddensTestParse_RecordsSelfURI/3.2_with_$self,/3.1_with_$selfandTestConformance/self-uri; deleting$self:from the fixture reddensTestConformance/self-urion the capability assertion and leaves the golden unrewritten —require.False(t, t.Failed())guards the snapshot from being rewritten behind a regression — while a byte-deletedselfURIkey is restored byte-identically by-update.make gategreen on 804b9ae, withmainmerged in: coverage at exactly 100%,golangci-lint0 issues. The two doc comments over the 100-word cap that failed the earlier CI run are rewritten.irVersionline, andTestCompatibleVersion's neighbour rows are re-anchored.Breaking
ir.IRVersionmoves from 0.7.0 to 0.8.0.SourceInfogainedselfURI, and ir-design §2.1 moves the version on any change to aDocument's JSON shape: a consumer built against 0.7.0 refuses the new member, so a document carrying it is unreadable there. The version history indocs/ir-design.mdrecords the entry. #734 and #735 also claim 0.8.0, so whichever of the three merges later moves to the next version.