lowering

package
v0.0.0-...-38da05c Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

Package lowering holds the context every OpenAPI lowering reads.

It is the substrate the lowering packages share, not a stage: it lowers and reports nothing itself. It owns the answer to "what is being lowered, and what does the document say about itself": the parsed document, the source's identity, the indexes derived once at entry, and the constructors that stamp provenance.

It is a package because every lowering package needs those answers, and only one beneath them all serves each: the schema walk may not reach the operation walk, which reaches it, and auth and document reach neither (micro-compiler-design §5.1).

Index

Constants

View Source
const BinaryInferenceHeuristic ir.Inferred = "binary-inference"

BinaryInferenceHeuristic is the name FileInfo.Inferred and PartEncoding.Inferred carry on a body or part read as a file because its media type is binary, rather than because its schema or application/octet-stream says so. It is a constant for the reason StreamingInferenceHeuristic is.

View Source
const DiscriminatorInferenceHeuristic ir.Inferred = "discriminator-inference"

DiscriminatorInferenceHeuristic is the name a Union's Provenance.Inferred carries where the discriminator-inference policy filled its Discriminator, and a subtype's where it read its DiscriminatorValue. It is a constant for the reason StreamingInferenceHeuristic is: an auditor greps for it.

View Source
const ExtensionPromotionHeuristic ir.Inferred = "extension-promotion"

ExtensionPromotionHeuristic is the name the node keeping a vendor extension lists once a typed field is read out of that extension. It is a constant because the marker is what an auditor greps for, and a spelling written at the producing site and again at a reading test can drift.

View Source
const GroupExtensionHeuristic ir.Inferred = "group-extension"

GroupExtensionHeuristic is the name Provenance.Inferred carries on an operation GroupByExtension filed by the path its extension states. OpenAPI gives an x-* key no meaning, so reading one as a group is a convention's reading, not the document's.

View Source
const GroupPathPrefixHeuristic ir.Inferred = "group-path-prefix"

GroupPathPrefixHeuristic is the name Provenance.Inferred carries on an operation GroupByPathPrefix filed. It is a constant for the reason StreamingInferenceHeuristic is: an auditor greps for it.

View Source
const HTTPDateInferenceHeuristic ir.Inferred = "http-date-inference"

HTTPDateInferenceHeuristic is the name a header's Provenance.Inferred carries where the HTTP-date policy set its Encoding. It is a constant for the reason StreamingInferenceHeuristic is: an auditor greps for it.

View Source
const IdempotencyInferenceHeuristic ir.Inferred = "idempotency-inference"

IdempotencyInferenceHeuristic is the name an Operation's Provenance.Inferred carries where the idempotency policy read its Idempotency off a header parameter. It is a constant for the reason StreamingInferenceHeuristic is: an auditor greps for it.

View Source
const MaxGroupPathDepth = 16

MaxGroupPathDepth bounds the segments of a group path, so the groups it nests: 16, a 2.3x margin over the 7 the golden spec's deepest writes (spec @e411be7e). Each group's ID spells the path to it, so the IDs of a path's groups weigh half its depth times its length, and the bound is that factor.

View Source
const NullableInferenceHeuristic ir.Inferred = "nullable-inference"

NullableInferenceHeuristic is the name ir.TypeRef.Inferred carries on a reference whose null the nullable-inference policy read in where the document's version does not. It is a constant for the reason StreamingInferenceHeuristic is: an auditor greps for it.

View Source
const PaginationInferenceHeuristic ir.Inferred = "pagination-inference"

PaginationInferenceHeuristic is the name an operation's Provenance.Inferred carries where the pagination-inference policy filled its Pagination. It is a constant for the reason StreamingInferenceHeuristic is: an auditor greps for it.

View Source
const ReplacementInferenceHeuristic ir.Inferred = "replacement-inference"

ReplacementInferenceHeuristic is the name a deprecated node's Provenance.Inferred carries where the replacement policy read its Deprecation.ReplacedBy out of the deprecation's message. It is a constant for the reason StreamingInferenceHeuristic is: an auditor greps for it.

View Source
const SecretInferenceHeuristic ir.Inferred = "secret-inference"

SecretInferenceHeuristic is the name a parameter's, a header's or a property's Provenance.Inferred carries where the secret policy set its Secret. It is a constant for the reason StreamingInferenceHeuristic is: an auditor greps for it.

View Source
const StreamingInferenceHeuristic ir.Inferred = "streaming-inference"

StreamingInferenceHeuristic is the name Provenance.Inferred carries on an operation whose streaming was read out of a media type rather than declared. It is a constant because the marker is what an auditor greps for, and a spelling written at the producing site and again at a reading test can drift.

Variables

This section is empty.

Functions

func AllowReserved

func AllowReserved(p Promoter, unmodeled ir.Unmodeled, prov *ir.Provenance) (bool, []ir.Diagnostic)

AllowReserved reports whether the extensions kept in unmodeled, a parameter's, ask by p's sources of TargetAllowReserved for its value's reserved characters to be sent unescaped, and marks prov when they do. The caller asks only of a parameter writing no `allowReserved`, which decides for itself.

func Beside

func Beside[T, S any, R chainable[T, S]](c Ctx, ref R, usePtr jsontext.Pointer, folds bool) (ir.Unmodeled, []ir.Diagnostic)

Beside returns what the Reference Objects of ref's chain write beside their $ref that the use does not read, keyed "openapi:reference/<i>/<key>": i is 0 for the use written at usePtr, then counts the aliases the chain passes, nearest first. folds says the use folds summary and description into docs.

func Carried

func Carried(p Promoter, own ir.Unmodeled, scopes ...string) ir.Unmodeled

Carried returns own with, for each key p reads that own does not hold unscoped, the entry of the first of scopes holding it beneath, keyed unscoped. It returns own itself where no scope adds a key. It reads a valued fact, which the nearest statement settles, the carrier's own first (docs/compilers/openapi.md#extension-promotion).

func CarrierScopes

func CarrierScopes(mediaType string) []string

CarrierScopes returns the scopes a parameter or a header keeps the keys of the objects it carries under, the nearest first: the content entry mediaType names and then that entry's schema, or the schema alone where mediaType is empty, the schema spelling (docs/ir/unmodeled.md#keys).

func ChargeExpansion

func ChargeExpansion(c Ctx, raw int)

ChargeExpansion charges the expansion raw more bytes that a lowering copies as raw values with no $ref naming them: what a path item keeps onto each of its additionalOperations entries, and the servers it names on them.

func ChargeExpansionAt

func ChargeExpansionAt(c Ctx, at jsontext.Pointer, node *yaml.Node)

ChargeExpansionAt charges the expansion one more copy of the declaration at node, written at at in c's document, that a lowering makes with no $ref naming it: an inline parameter of a path item, at each additionalOperations entry that takes it (GitHub #1428). It weighs the copy as Declared weighs a $ref's. Whether the copies have crossed the budget is ExpansionCrossed's to say.

func DefaultBinaryMediaTypes

func DefaultBinaryMediaTypes() []string

DefaultBinaryMediaTypes is the list the policy uses when the caller states none. It is a default and not a standard: it names registered binary types, and top-level types whose members are binary but for rare text ones such as an ASCII image/vnd.dxf. A caller who reads them otherwise names its own list.

func DefaultExtensionPromotions

func DefaultExtensionPromotions() map[ExtensionTarget][]ExtensionSource

DefaultExtensionPromotions is the mapping the policy uses when the caller states none. It is a default and not a standard: OpenAPI defines none of these keys, and each is simply the spelling that has become common for a field the format never gave a keyword. A document using another spelling is not wrong — it names its own mapping.

func DefaultStreamingMediaTypes

func DefaultStreamingMediaTypes() []string

DefaultStreamingMediaTypes is the list the policy uses when the caller states none. It is a default and not a standard: `text/event-stream`, `application/json-seq` (RFC 7464) and the `+json-seq` suffix (RFC 8091) are registered, and the two JSON-lines spellings are conventions that happen to be what generators in this space already look for. A document using another spelling is not wrong — it names its own list.

func DropContained

func DropContained(p Promoter, u *ir.Unmodeled, whole ...string)

DropContained removes from u each entry that another entry of u holds whole: its provenance lies in the same source strictly beneath the other's, and its value is the value found there inside the other's. An entry naming a key p reads stays, unscoped or beneath any scope, since a promotion reads the kept entries and one inside another's value reaches no field (docs/ir/unmodeled.md#promotion). With whole set, only those entries are asked whether they hold another.

func EncodingRules

func EncodingRules(c Ctx) oas.EncodingRules

EncodingRules returns the Encoding Object's rows an encoding c lowers is read with (rowsOf), as SchemaRules returns the Schema Object's: what a part takes where its encoding leaves a field unwritten.

func EnumOpenness

func EnumOpenness(p Promoter, unmodeled ir.Unmodeled, closed *bool, prov *ir.Provenance) []ir.Diagnostic

EnumOpenness clears *closed, an enum's or that of the union a mixed enum lowers to, when the vendor extensions kept in unmodeled state the set open by p's sources of TargetEnumOpen, and marks prov with the heuristic when they do.

The key's presence is the statement, so every value shape but an explicit `false` reads as open (extensionOpenness).

A document writing x-extensible-enum instead of `enum` lowers to no ir.Enum, so there is nothing to open. Minting an enum from a member-list extension is out of scope; the entry survives verbatim for a consumer that wants it (GitHub #427).

func ExpansionCrossed

func ExpansionCrossed(c Ctx) bool

ExpansionCrossed reports whether the copies made so far weigh past the budget, for a lowering to ask before it makes one more: the document is then refused (Ctx.ExpansionRefusal), so nothing more need copy.

func GroupStability

func GroupStability(p Promoter, unmodeled ir.Unmodeled, tier *ir.Stability, inferred *ir.Inferred) []ir.Diagnostic

GroupStability fills tier from the vendor extensions kept in unmodeled, as Stability does, and records the heuristic in inferred: a group has no Provenance to mark.

func HoldsOneDocument

func HoldsOneDocument(mediaType string) bool

HoldsOneDocument reports whether mediaType names a syntax whose body is one document, JSON's or XML's, by name or structured suffix (RFC 6839, RFC 7303). It answers only for those two: which other media types repeat a structure is not a closed set, as vendor types and multipart/mixed show.

func ListsValues

func ListsValues(target ExtensionTarget) bool

ListsValues reports whether a source of target may list the values that state its fact (ExtensionSource.Values): a target stating that something is so, or marking where a page walk's value sits, and not one reading a text, a name or a tier, which a list of values could only narrow.

func NameAt

func NameAt(c Ctx, pointer jsontext.Pointer) string

NameAt returns the hint the node built at pointer in c's document is named by (naming.Namer.At): a function of the documents and the coordinate alone, whichever lowering builds the node, read once for every copy of c.

func NameOfDocument

func NameOfDocument(c Ctx, doc bind.DocID) string

NameOfDocument returns the hint what is declared at the root of document doc of the bindings' table is named by (naming.Namer.Document).

func NameThrough

func NameThrough(c Ctx, pointer jsontext.Pointer) string

NameThrough returns the name the $ref written at pointer in c's document suggests (naming.Namer.Through), and "" where it suggests none.

func NameTitle

func NameTitle(c Ctx, pointer jsontext.Pointer) (string, bool)

NameTitle returns the name the title of the schema at pointer in c's document gives the node built there (naming.Namer.Title), and false where it gives none.

func NormalizeMediaType

func NormalizeMediaType(mediaType string) string

NormalizeMediaType reduces a media type to the form a classification compares: lowercased, parameters dropped, surrounding space trimmed. RFC 6838 §4.2 makes the type and subtype case-insensitive, and a parameter states how a body is encoded rather than naming another type.

Every classification reads this one rule, so a policy and a lowering cannot drift apart. The IR never records the result: a caller normalizes a copy, and the IR keeps the spelling the document wrote.

func OtherIDs

func OtherIDs(c Ctx) []ids.Document

OtherIDs returns how the IDs of what each document a reference read beside the source declares name it, in the order Document.Sources lists them: the documents whose namespaces the compile declares beside the source's.

func Remembered

func Remembered[K comparable, V any](c Ctx, key K, read func() V) V

Remembered returns read's answer for key, read once and remembered for every copy of c. read must turn only on the documents and their bindings, which no lowering changes, and key on all else it turns on; a package's own key type keeps its readings from another's. Each type of key and answer has a map of its own, so neither is boxed to be found or kept, and a key read for two types of answer is read once for each.

func SchemaRulesAt

func SchemaRulesAt(c Ctx, pointer jsontext.Pointer) oas.SchemaRules

SchemaRulesAt returns the rows the schema at pointer of c's document is read with: those of the dialect the innermost schema resource root at or above it names, where one does (load.Dialects.At), and c's otherwise (SchemaRules).

func SchemaRulesIn

func SchemaRulesIn(c Ctx, id bind.DocID) oas.SchemaRules

SchemaRulesIn returns the rows the schemas document id of the bindings' table declares are read with, for a reading that crosses a $ref without a context of that document: the source's own for the source, and for one the compile did not read beside it.

func SchemaRulesOf

func SchemaRulesOf(c Ctx, n *yaml.Node) oas.SchemaRules

SchemaRulesOf is SchemaRulesAt for a reading that has the schema's node n and not where it is: the rows load.Dialects.Of gives it, and the source's own for a node it gives none, whatever document c reads, so a reading that follows a $ref into another document still reads its schemas in their own dialect. An aliased node reads one dialect wherever it is placed.

func ServerName

func ServerName(p Promoter, unmodeled ir.Unmodeled, prov *ir.Provenance) (string, []ir.Diagnostic)

ServerName reads from unmodeled, a server's, the name p's sources of TargetServerName state, and marks prov when it returns one. The caller asks only of a server its document names in no other way: a name the document declares is its own, and no key's.

func Settled

func Settled[S any](c Ctx, build func() *S) *S

Settled returns the run's store of type S, which build makes on the first ask of any copy of c, for what settlements (compile.Settlement) read of the registry. Remembered may not keep such a reading, as it reads what the settlements before it left: it is sound only while no settlement after it rewrites what it read. The run takes every completion (compile.Types.Complete) before any deferred settlement, so a store only deferred settlements fill is sound where only completions rewrite what it reads. S's documentation names them, and each reports a store it finds filled.

func Shadowed

func Shadowed(p Promoter, own ir.Unmodeled, scopes ...string) []ir.Unmodeled

Shadowed returns, for each of scopes holding one, the entries own holds beneath it for a key p reads that the carrier's own key or a nearer scope states too, keyed unscoped: the statements Carried passes over. A carrier reads each for its findings alone, so a misfit behind a nearer statement of its key is reported once, at its own key. It returns nil where Carried passes over nothing.

func ShapeOf

func ShapeOf(raw ir.RawValue) string

ShapeOf names the kind of raw, a value in the IR's canonical form, as a report spells it.

func Stability

func Stability(p Promoter, unmodeled ir.Unmodeled, tier *ir.Stability, prov *ir.Provenance) []ir.Diagnostic

Stability fills tier from the vendor extensions kept in unmodeled, by p's sources of TargetStability, and marks prov with the heuristic when it does.

func TokenEndpointAuthMethods

func TokenEndpointAuthMethods(p Promoter, unmodeled ir.Unmodeled, inferred *ir.Inferred) ([]string, []ir.Diagnostic)

TokenEndpointAuthMethods reads from unmodeled, an OAuth flow's, the ways a client authenticates to its token endpoint, by p's sources of TargetTokenEndpointAuthMethods, and marks inferred when it returns any. A string is one method and a list of strings several; a list holding empty text or a method twice is a misfit, as the field is a set of names, and so is any other value. Nothing checks a method against the registry, which is open.

func UnformedTier

func UnformedTier(p Promoter, tag string, unmodeled ir.Unmodeled) []ir.Diagnostic

UnformedTier reports each key p reads a tier from that the tag named tag keeps in unmodeled, where the tag forms no operation group: the tier is read through the group alone, so it fills no stability.

func UnheldDeprecation

func UnheldDeprecation(p Promoter, tag string, formed bool, unmodeled ir.Unmodeled) []ir.Diagnostic

UnheldDeprecation reports each key p reads a deprecation or its members from that the tag named tag keeps in unmodeled, where those keys state one: a tag and the group it forms hold no deprecation, so it fills nothing. A source listing values is reported where its value is one of them, as a tier the same key states is the group's, and a key UnformedTier reports, where the tag forms no group, is not reported again.

func UnionOpenness

func UnionOpenness(p Promoter, unmodeled ir.Unmodeled, closed *bool, prov *ir.Provenance) []ir.Diagnostic

UnionOpenness clears *closed, that of a union a oneOf or anyOf lowers to, when the vendor extensions kept in unmodeled state the union open by p's sources of TargetUnionOpen, and marks prov with the heuristic when they do, as EnumOpenness opens an enum.

func Unpromoted

func Unpromoted(key string, at ir.Provenance, why, outcome string) ir.Diagnostic

Unpromoted is the info diag.UnpromotedExtension reporting the key key at at, which states nothing usable, for why, so outcome.

func UnreadExtensions

func UnreadExtensions(c Ctx, doc *ir.Document) []ir.Diagnostic

UnreadExtensions reports each vendor extension doc keeps under a prefix c's promotion policy owns that the compiler reads no key of, naming the nearest key it reads, as the likeliest one it misspells. The keys read are each reader's own: the promotion mapping's (Promoter.Keys) and grouping's (GroupingExtension.Keys). doc is the whole document, every node's Unmodeled read once; an extension inside an entry kept verbatim, such as an allOf branch, is a value of that entry and is not read.

Types

type BinaryInference

type BinaryInference struct {
	// MediaTypes replaces the default list rather than extending it. Empty
	// means the default.
	//
	// Entries are matched as StreamingInference's are, case-insensitively and
	// without parameters, an entry starting with `+` naming a structured
	// suffix. An entry `type/*` matches each media type of that type whose
	// subtype has no structured suffix, since a suffix names the syntax the
	// body is written in: `image/*` matches `image/png`, not `image/svg+xml`.
	MediaTypes []string `json:"mediaTypes,omitempty"`
	// Disabled turns the inference off: a body or part is then a file only
	// where its schema or application/octet-stream declares one.
	Disabled bool `json:"disabled,omitzero"`
}

BinaryInference is the binary media-type policy: which media types mean "this body is a file" where its schema says no more than that it is a string.

It is a policy rather than a table in the lowering because the reading is a guess (architecture principle 6). OpenAPI says any binary media type marks binary content, but no registry says which types are binary, so a list is a judgment a caller may not share. application/octet-stream is not on it: RFC 2046 defines that type as arbitrary octets, so the lowering reads it as declared, whatever this says.

type Ctx

type Ctx struct {
	// Doc is the parsed, reference-resolved source document. Lowering reads it
	// and never writes through it.
	Doc *soa.OpenAPI
	// Source is the identity of the loaded source, stamped into Document.Sources.
	Source ir.SourceInfo
	// SrcIndex is this source's index within the compile, stamped into every
	// Provenance.
	SrcIndex int
	// Grouping selects how operations are grouped into OperationGroups. It is one
	// of the caller policies the context carries (Policy).
	//
	// It arrives as the caller wrote it, normalized or not — the compiler's
	// Options fills an unset one in before building a context, but nothing here
	// enforces that. A strategy the operation lowering does not recognize groups
	// by tags, which is what makes the unnormalized zero value harmless rather
	// than a second spelling of the default to keep in step.
	Grouping GroupingStrategy
	// GroupingExtension is what GroupByExtension reads, arriving resolved as
	// Grouping does: the compiler's Options fills in the default extension.
	GroupingExtension GroupingExtension
	// Limits is the caller's budget for the constructs the walk builds. Like
	// Grouping it arrives already resolved: the compiler's Options fills the
	// unset budgets in and translates its own spelling of "unbounded" before
	// building a context, so the zero value here simply bounds nothing.
	Limits Limits

	// NullableInference is the nullable-inference policy, and
	// DiscriminatorInference the discriminator-inference policy, beside the
	// policies of what a document's names and messages imply, read once it is
	// whole. They sit before foreign so all of them share a word.
	NullableInference      NullableInference
	DiscriminatorInference DiscriminatorInference
	IdempotencyInference   IdempotencyInference
	SecretInference        SecretInference
	HTTPDateInference      HTTPDateInference
	ReplacementInference   ReplacementInference
	PaginationInference    PaginationInference
	// contains filtered or unexported fields
}

Ctx is everything a lowering may read: the parsed document, the caller's policies, the source's identity, and the indexes derived from them once at entry. New builds one; the zero Ctx is invalid.

It is a value: a function taking one takes a copy, and every lowering takes it as a parameter (#177). Of what copies share, only expansion changes an answer: past its budget, no $ref resolves. The maps stay unexported because a copy shares a map, which an exported one would let a callee write through.

Call sites bind it to c: ctx names the context.Context a Compile takes.

func Declared

func Declared[T, S any, R chainable[T, S], P interface {
	*T
	GetRootNode() *yaml.Node
}](c Ctx, ref R, usePtr jsontext.Pointer) (*T, Ctx, jsontext.Pointer)

Declared returns what the entry ref, written at usePtr in c's document, resolves to, with the context its declaration is lowered in and the pointer declaring it there: the position the chain of its Reference Object ends on, in whichever document (InDocument), as the bindings' table places it, or, for an inline entry, c and usePtr themselves. Past Limits.MaxReferenceExpansion a $ref resolves to nothing (Ctx.ExpansionRefusal).

func InDocument

func InDocument(c Ctx, id bind.DocID) (Ctx, bool)

InDocument returns c for lowering what document id of the bindings' table declares, at that document's own coordinates: the source's (InScope), or another's, whose references are read in its scope, whose positions are its own, so each Provenance names it, and whose IDs it qualifies. It is false, c unchanged, for a document the compile did not read beside the source.

func New

func New(srcIndex int, doc *load.Document, p Policy) Ctx

New derives the context for doc, at srcIndex, under p. doc must not be nil: the compiler lowers only a document its load returned.

The schema-name index is built here, not on first use, so every reader sees the same set whatever the source order: a $ref resolved mid-lowering must see a component declared later. The streaming and binary policies are normalized here so readers cannot disagree about a media type, and the promotion policy is copied so no lowering can write through the context into the caller's map.

func (Ctx) Bindings

func (c Ctx) Bindings() *typed.Bindings

Bindings returns where the document's schema $refs land, as the load phase resolved them.

func (Ctx) DeclaresSchema

func (c Ctx) DeclaresSchema(name string) bool

DeclaresSchema reports whether the document declares a component schema of this name. A name it does not declare is not a resolvable $ref target.

func (Ctx) DiagAt

func (c Ctx) DiagAt(sev ir.Severity, code string, pointer jsontext.Pointer, format string, args ...any) ir.Diagnostic

DiagAt builds one diagnostic at pointer, stamped with this compile's source index.

It returns rather than records. Those are two different jobs, and separating them is what lets both rules hold at once: GitHub #86 wants provenance built in exactly one place, because hand-writing it is how a diagnostic shipped with none (GitHub #43); micro-compiler-design §4 wants diagnostics returned rather than accumulated through a handle, because accumulation is the side effect the conversion exists to remove. A constructor that stamps and hands back satisfies both, and a lowering that has no accumulator yet can still be sure of its provenance.

func (Ctx) DynamicAnchor

func (c Ctx) DynamicAnchor(name string) bind.DynamicAnchor

DynamicAnchor returns what c's document's declarations of the $dynamicAnchor name say (bind.Table.DynamicAnchor).

func (Ctx) ExpansionRefusal

func (c Ctx) ExpansionRefusal() (ir.Diagnostic, bool)

ExpansionRefusal returns the error refusing the document when the copies its $refs and path items made weighed past Limits.MaxReferenceExpansion, and false when they did not. It is meant to be asked once every lowering has returned: a copy past the budget lowers nothing, so a crossing after the question goes unreported.

func (Ctx) IDs

func (c Ctx) IDs() ids.Document

IDs returns the document c's positions are in, as the IDs of what it declares name it (see InDocument).

func (Ctx) InScope

func (c Ctx) InScope(scope resolve.Scope) Ctx

InScope returns c for lowering at the source's coordinates what is read in scope, the source's own content (resolve.Scope.InSource). What another document declares is lowered in its coordinates instead (InDocument).

func (Ctx) MediaTypeBinary

func (c Ctx) MediaTypeBinary(mediaType string) bool

MediaTypeBinary reports whether the policy classifies mediaType as binary. It is a predicate rather than a getter for the reason MediaTypeStreams is.

func (Ctx) MediaTypeStreams

func (c Ctx) MediaTypeStreams(mediaType string) bool

MediaTypeStreams reports whether the policy classifies mediaType as a stream of frames. It is a predicate rather than a getter because handing back the set would make it writable through a copy of the context.

func (Ctx) MediaTypeUse

func (c Ctx) MediaTypeUse(media *soa.MediaType) (*resolve.ReferencedMediaType, bool)

MediaTypeUse returns the model the load phase built of media, a content entry, and whether media is written as a $ref (load.MediaTypes.Use).

func (Ctx) Place

func (c Ctx) Place() provenance.Doc

Place returns where c places a pointer of its document: in another document's own Document.Sources entry, for one InDocument reads, and otherwise in the source's, the overlay named as its writer for a position the overlay introduced or rewrote.

Every lowering places a pointer through it, entities and diagnostics alike (GitHub #86), so no lowering spells a source index, and an overlay's contribution is traced without touching any of them.

func (Ctx) Position

func (c Ctx) Position(pointer jsontext.Pointer) bind.Position

Position returns where pointer of c's document is in the bindings' table.

func (Ctx) Promoter

func (c Ctx) Promoter() Promoter

Promoter returns the vendor-extension promotion policy this context carries.

func (Ctx) Reached

func (c Ctx) Reached(pointer jsontext.Pointer) bool

Reached reports whether a lowering run under this context, or any copy of it, resolved a reference to pointer in the source. It is meant to be asked once every lowering that follows a reference has returned: before that it answers for those that have.

func (Ctx) RefScope

func (c Ctx) RefScope() resolve.Scope

RefScope is the context seen as a reference-resolution scope: the document's own path, what it declares, and the parsed document itself.

It is derived on use rather than stored beside the context. A stored copy would be a second place the same facts live, free to disagree with the context after any change to it — and the whole point of the context is that there is one answer.

func (Ctx) SchemaRules

func (c Ctx) SchemaRules() oas.SchemaRules

SchemaRules returns the Schema Object's rows of the document whose content c reads (rowsOf). A reading only a minor decides, such as a required `items` or the effect `nullable` has, asks these rather than the version; a keyword's shape, which a schema's dialect decides, asks SchemaRulesAt.

func (Ctx) Siblings

func (c Ctx) Siblings() load.Siblings

Siblings returns the fields the load phase modelled beside the document's path item $refs (see New). A load.Siblings only answers questions, so handing it out lets no copy of c change what another reads.

func (Ctx) Sources

func (c Ctx) Sources() []ir.SourceInfo

Sources is the document's input files, in the order Provenance.Source indexes them: the source being lowered, then the overlay applied to it if there was one, then each document a reference read beside it (load.Others).

It is built here rather than by the compiler that assembles the Document because the two facts it joins are already the context's, and a second place that pairs a source index with a SourceInfo is a second place they can disagree — which would misattribute every node rather than fail.

type DiscriminatorInference

type DiscriminatorInference struct {
	// Disabled turns the reading off: an unmapped discriminator then routes by
	// component name, a subtype it routes by name keeping that name as its tag,
	// and an undeclared union stays untagged, as the document says.
	Disabled bool `json:"disabled,omitzero"`
}

DiscriminatorInference is the discriminator-inference policy: whether a union's tags are read off the strings each variant pins its tag property to, where the document declares no mapping or no discriminator, and a subtype's off the strings it admits, where it is routed by name.

It is a policy because the reading guesses at intent (architecture principle 6): OpenAPI routes an unmapped discriminator by component name, which a variant or subtype pinning other values rejects, and an undeclared union names its variant only by validation, though a required property its variants pin apart tells them apart as a tag would.

func (DiscriminatorInference) Honours

func (p DiscriminatorInference) Honours() bool

Honours reports whether the policy is on, so that a union's tag is read off the values its variants pin, and a subtype's off those it admits.

type ExtensionLists

type ExtensionLists string

ExtensionLists is what a list value of a grouping extension means. A string is one path either way, its segments separated by dots.

const (
	// ListsAreSegments reads a list as one path, each entry adding its
	// segments, as x-fern-sdk-group-name writes one.
	ListsAreSegments ExtensionLists = "segments"
	// ListsAreGroups reads a list as several paths, each a group the operation
	// belongs to, as x-speakeasy-group writes them. The operation is filed under
	// the first, and a group is minted for each of the rest, for the remount a
	// consumer reads from the extension, which stays kept.
	ListsAreGroups ExtensionLists = "groups"
)

The readings of a list value.

type ExtensionPromotions

type ExtensionPromotions struct {
	// Disabled turns promotion off. Off means off: every extension is kept
	// verbatim and no typed field is written from one.
	Disabled bool `json:"disabled,omitzero"`
	// Targets replaces the default map rather than extending it, so a caller who
	// states a mapping gets exactly that mapping. Empty means the default. Each
	// list is in order of precedence: the first source stating a value fills the
	// field, and a later one stating another is reported.
	Targets map[ExtensionTarget][]ExtensionSource `json:"targets,omitempty"`
	// Prefixes are the extension name prefixes the policy owns: a key under one
	// that neither a source nor grouping reads is reported, naming the nearest
	// key they read, as it is most likely that key misspelt (UnreadExtensions).
	// None is owned by default.
	Prefixes []string `json:"prefixes,omitempty"`
}

ExtensionPromotions is the vendor-extension promotion policy: which x-* keys are read into which typed IR field.

It is a policy rather than a table in the lowering because OpenAPI assigns an x-* key no semantics whatsoever, so reading one as anything is a guess about a convention (architecture principle 6). The node keeping the extension lists ExtensionPromotionHeuristic and the extension stays in Unmodeled untouched, which is what makes the guess auditable and reversible: a consumer that disagrees can ignore the typed field and read the entry itself.

func (ExtensionPromotions) Check

func (p ExtensionPromotions) Check() error

Check refuses a policy that would read less than it says: a target outside the vocabulary, a source naming no extension, values listed for a target that reads none, an owned prefix that is no extension's, or a mapping beside Disabled, which reads nothing. A refusal is the caller's mistake and not the document's, so it is an error and no diagnostic.

type ExtensionSource

type ExtensionSource struct {
	// Key is the extension name as the document writes it, x- prefix included.
	Key string `json:"key"`
	// Member names a member of the key's object value, or is empty to read the
	// value whole.
	Member string `json:"member,omitempty"`
	// Values lists the values that state the target's fact, for a target that
	// reads one (ListsValues), each compared with a string's text or a boolean's
	// or number's JSON spelling. Empty reads the target's own vocabulary. A value
	// it does not list states nothing, reported where no other source reads it
	// off the same member of the key.
	Values []string `json:"values,omitempty"`
}

ExtensionSource is one place a policy reads a fact from: the extension Key and, where that key's value is an object holding several facts, the Member of it that holds this one.

The two are fields rather than a joined path because an extension name may hold any character a path separator would be.

func (ExtensionSource) String

func (s ExtensionSource) String() string

String spells s as a report names it.

type ExtensionTarget

type ExtensionTarget string

ExtensionTarget names one typed IR field a vendor extension can be read into.

It is a closed vocabulary rather than a free-form path because a promotion has to be applied by code that knows the field's type, and a name nothing implements would be a policy that silently does nothing, which is why ExtensionPromotions.Check refuses one (Targets lists the vocabulary).

const (
	// TargetDeprecation deprecates what a key sits on where no `deprecated`
	// keyword did, giving the members below a Deprecation to fill. The text
	// "deprecated" or a boolean true states it, and false or another word states
	// nothing, unless the source lists the values that state it
	// (ExtensionSource.Values), as the default does for its stability keys.
	TargetDeprecation ExtensionTarget = "deprecation"
	// TargetDeprecationMessage fills ir.Deprecation.Message.
	TargetDeprecationMessage ExtensionTarget = "deprecation.message"
	// TargetDeprecationSince fills ir.Deprecation.Since.
	TargetDeprecationSince ExtensionTarget = "deprecation.since"
	// TargetDeprecationRemovalVersion fills ir.Deprecation.RemovalVersion. No
	// default key names it: the one convention in wide use for a scheduled
	// removal, x-sunset, states a date, and a document that spells a removal
	// *version* names its own key.
	TargetDeprecationRemovalVersion ExtensionTarget = "deprecation.removalVersion"
	// TargetDeprecationRemovalDate fills ir.Deprecation.RemovalDate.
	TargetDeprecationRemovalDate ExtensionTarget = "deprecation.removalDate"
	// TargetDeprecationReplacedBy fills ir.Deprecation.ReplacedBy with what a key
	// names as replacing what it sits on: a string or a list of strings, each the
	// name the document gives an entity of that node's class. No default key
	// names it, since no spelling for a replacement has become common; a document
	// that writes one names its own mapping.
	TargetDeprecationReplacedBy ExtensionTarget = "deprecation.replacedBy"

	// TargetEnumOpen clears ir.Enum.Closed, or a mixed enum's ir.Union.Closed,
	// saying the member set admits values the document does not list.
	//
	// It names the fact rather than the field, unlike the rest of this
	// vocabulary: a schema's `enum` is closed by definition, so openness is the
	// only half of that bool a document declares, and a target named for Closed
	// could only be written false and would read as its own opposite.
	//
	// The key's presence is the statement, since x-extensible-enum writes the
	// member list as its value. A `false` is honoured (extensionOpenness); a
	// source listing Values opens it on those alone.
	TargetEnumOpen ExtensionTarget = "enum.open"

	// TargetUnionOpen clears the ir.Union.Closed of a oneOf or an anyOf, saying
	// a payload may hold a variant the union does not list. It names the fact
	// for TargetEnumOpen's reason: a oneOf or anyOf is closed by definition. No
	// default key names it, since no spelling for an open union has become
	// common; a document that writes one names its own mapping.
	TargetUnionOpen ExtensionTarget = "union.open"

	// TargetStability fills ir.Operation.Stability. The words a value may use
	// are stabilityTier's.
	TargetStability ExtensionTarget = "stability"

	// TargetRedaction asks for a value to be redacted, as `format: password`
	// does: ir.TypeCommon.Sensitive on a type node, Secret on a property or a
	// parameter. A boolean true states it and false states nothing, so a false
	// clears no keyword and no $ref target's key. It can hide a true on the schema
	// of its own parameter or header, as the two share one entry (GitHub #396).
	TargetRedaction ExtensionTarget = "redaction"

	// TargetAllowReserved sets the ir.HTTPParamBinding.AllowReserved of a
	// parameter writing no `allowReserved`, which states it itself where OpenAPI
	// applies it. A boolean true states it and false states nothing. No default
	// key names it, as no spelling has become common.
	TargetAllowReserved ExtensionTarget = "parameter.allowReserved"

	// TargetServerName names an ir.Server whose document gives it no name, which
	// below OpenAPI 3.2 none can: a 3.2 `name` is the document's own and wins.
	TargetServerName ExtensionTarget = "server.name"

	// TargetTokenEndpointAuthMethods fills ir.OAuthFlow.TokenEndpointAuthMethods
	// from a string or a list of strings on the flow, each as the IANA registry
	// of token endpoint authentication methods spells it. No OpenAPI field
	// states it, and no default key names it, since no spelling has become
	// common.
	TargetTokenEndpointAuthMethods ExtensionTarget = "oauthFlow.tokenEndpointAuthMethods"
)

The typed fields promotion can fill today. Every other field an extension is the only OpenAPI spelling for is a target this vocabulary is meant to grow, not a decision against it (GitHub #252): docs/ir/unmodeled.md#promotion lists them with the node each promotion records itself on.

const (
	// TargetPaginationCursor is the input a cursor walk sends the next cursor
	// in, ir.Pagination.InputCursor of strategy cursor.
	TargetPaginationCursor ExtensionTarget = "pagination.cursor"
	// TargetPaginationOffset is the input an offset walk sends its item offset
	// in, InputCursor of strategy offset.
	TargetPaginationOffset ExtensionTarget = "pagination.offset"
	// TargetPaginationPage is the input a page walk sends its page number in,
	// InputCursor of strategy page.
	TargetPaginationPage ExtensionTarget = "pagination.page"
	// TargetPaginationLimit is the page-size input, InputLimit.
	TargetPaginationLimit ExtensionTarget = "pagination.limit"
	// TargetPaginationItems is where a page's items sit, Items.
	TargetPaginationItems ExtensionTarget = "pagination.items"
	// TargetPaginationNextCursor is the next cursor in a page, NextCursor.
	TargetPaginationNextCursor ExtensionTarget = "pagination.nextCursor"
	// TargetPaginationHasMore is the flag in a page saying another page
	// follows, HasMore, which ends the walk where it is false, null or absent.
	TargetPaginationHasMore ExtensionTarget = "pagination.hasMore"
	// TargetPaginationNextLink is the next page's link in a page, NextLink, a
	// walk of strategy next_link where no input continues it.
	TargetPaginationNextLink ExtensionTarget = "pagination.nextLink"
	// TargetPaginationTotalCount is the count of every item, TotalCount.
	TargetPaginationTotalCount ExtensionTarget = "pagination.totalCount"
	// TargetPaginationTotalPages is the count of every page, TotalPages.
	TargetPaginationTotalPages ExtensionTarget = "pagination.totalPages"
)

The pagination an extension declares, one target a field of ir.Pagination. A source listing no Values holds a runtime expression naming the value, as a link's parameters do; one listing Values marks the parameter, member or type it sits on as that value (docs/compilers/openapi.md#extension-pagination).

const (
	// TargetStreamTerminator fills ir.StreamDetail.Terminator, from a key on a
	// streaming content of a success response or on the operation.
	TargetStreamTerminator ExtensionTarget = "stream.terminator"
	// TargetStreamCondition fills ir.StreamDetail.Condition from a key on the
	// operation holding an expression that names an input of its request.
	TargetStreamCondition ExtensionTarget = "stream.condition"
)

The targets filling an operation's ir.StreamDetail (docs/compilers/openapi.md#streaming-media).

const TargetParamChoices ExtensionTarget = "operation.paramChoices"

TargetParamChoices fills ir.Operation.ParamChoices from a key on the operation naming alternatives among its parameters (docs/compilers/openapi.md#mutually-exclusive-parameters).

func Targets

func Targets() []ExtensionTarget

Targets returns the vocabulary, every target a policy may name, sorted.

type GroupingExtension

type GroupingExtension struct {
	// Key is the extension read, x- prefix included. Empty reads none.
	Key string `json:"key,omitempty"`
	// Lists is what a list value means under Key. Any value but ListsAreGroups
	// reads one as ListsAreSegments; the compiler's options refuse a Key that
	// names none.
	Lists ExtensionLists `json:"lists,omitempty"`
	// Aliases is the extension listing an operation's aliases, each an object
	// stating a further group path under Key (AliasPaths). A group is minted for
	// each, for a remount to name, and no operation is filed in it, so no
	// GroupExtensionHeuristic marks it: a group has no provenance. Empty reads
	// none. An embedded-policy mapping reading the extension into AlsoMount is
	// its second reader, and must name this key for its mounts to name these
	// groups.
	Aliases string `json:"aliases,omitempty"`
	// Fallback groups an operation Key states no path for: GroupByTags or
	// GroupByPathPrefix, any other value, empty included, grouping by tags.
	Fallback GroupingStrategy `json:"fallback,omitempty"`
}

GroupingExtension is what GroupByExtension reads: which extension states an operation's group path, what a list there means, which extension lists the further paths it is exposed under, and how an operation stating none is grouped. Conventions disagree on a list, so its reading is the key's and is never assumed from another key's.

func DefaultGroupingExtension

func DefaultGroupingExtension() GroupingExtension

DefaultGroupingExtension returns the extension GroupByExtension reads where the caller names none: x-fern-sdk-group-name, whose list is one path, beside x-forge-aliases, whose entries restate it for each alias. It is a default and not a standard, as DefaultExtensionPromotions is.

func (GroupingExtension) AliasPaths

func (g GroupingExtension) AliasPaths(raw ir.RawValue) ([][]string, bool)

AliasPaths reads the group paths raw, the Aliases extension's value as Unmodeled keeps it, names: a list of objects, each stating paths under Key as Key's own value does (Paths). An object without Key, an empty list and null state none. It returns false for a misfit: any other value, an entry that is no object, or one whose paths are a misfit, the list judged whole as Paths judges one.

func (GroupingExtension) Keys

func (g GroupingExtension) Keys(strategy GroupingStrategy) []string

Keys returns the extensions grouping reads under strategy: Key and Aliases, each where it names one, under GroupByExtension, and none under any other strategy. It is the one list of them, so the lowering filing operations and the audit of an owned prefix (UnreadExtensions) read the same keys.

func (GroupingExtension) Paths

func (g GroupingExtension) Paths(raw ir.RawValue) ([][]string, bool)

Paths reads the group paths raw states, an extension's value as Unmodeled keeps it, each outermost segment first: one under ListsAreSegments, each entry's under ListsAreGroups, the first being the one the operation is filed under. Empty text, an empty list and null state none. It returns false for a misfit: any other value, or a path holding an empty segment, which no group is named by, or one deeper than MaxGroupPathDepth. A list is a misfit if any entry is, since the value is the document's whole statement.

type GroupingStrategy

type GroupingStrategy string

GroupingStrategy selects how operations are grouped into OperationGroups. It is the injectable-policy seam (architecture principle 6): grouping is inferred policy, not source semantics, and can be switched or disabled.

The vocabulary is declared here, below both walks, and re-exported by the compiler's public options rather than restated there. One declaration is what keeps the two spellings from drifting apart: a strategy the public type names and the lowering does not recognize would silently fall through to the default, and nothing would report it.

const (
	// GroupByTags groups operations by their first OpenAPI tag (default).
	GroupByTags GroupingStrategy = "tags"
	// GroupByPathPrefix groups operations by the first path segment.
	GroupByPathPrefix GroupingStrategy = "path-prefix"
	// GroupByExtension groups operations by the group path a vendor extension
	// states, nesting a group for each segment, and an operation stating none by
	// GroupingExtension.Fallback.
	GroupByExtension GroupingStrategy = "extension"
)

Grouping strategies.

type HTTPDateInference

type HTTPDateInference struct {
	// Disabled turns the reading off: such a header's text is then the one its
	// format names.
	Disabled bool `json:"disabled,omitzero"`
}

HTTPDateInference is the HTTP-date policy: whether a response header whose field an RFC defines as an HTTP-date, and whose schema declares a date-time with no encoding, is written and read as an HTTP-date.

It is a policy because the reading departs from the document (architecture principle 6): `format: date-time` spells RFC 3339's text, which the field's own definition rules out.

func (HTTPDateInference) Honours

func (p HTTPDateInference) Honours() bool

Honours reports whether the policy is on, so that the field's definition gives the header its text.

type IdempotencyInference

type IdempotencyInference struct {
	// Disabled turns the reading off: the header is then a parameter like any
	// other, and the operation's idempotency what the document declares.
	Disabled bool `json:"disabled,omitzero"`
}

IdempotencyInference is the idempotency policy: whether an operation declaring an `Idempotency-Key` header parameter, and no idempotency, takes that parameter as its idempotency token.

It is a policy because the reading guesses at intent (architecture principle 6): OpenAPI has no field for a token, and a header's name is all that says the server reads one.

func (IdempotencyInference) Honours

func (p IdempotencyInference) Honours() bool

Honours reports whether the policy is on, so that the header names the operation's idempotency token.

type Limits

type Limits struct {
	// MaxEnumMembers bounds the members of a single enum.
	MaxEnumMembers budget.Limit
	// MaxReferenceExpansion bounds what the declarations $refs name weigh,
	// summed over every $ref that lowers a copy of one, and what path items
	// copy onto their additionalOperations entries (see expansion).
	MaxReferenceExpansion budget.Limit
}

Limits is the share of the compiler's resource budgets the lowering enforces: those measuring a construct the walk builds, not the source document the load phase measures first.

It is separate from the public openapi.Limits, as load.Options is from openapi.Options: that type is a published contract, and most of it describes phases this one cannot see. The compiler projects one onto the other at entry, resolving each default and the public spelling of "unbounded" there (budget.FromOption), so the zero value bounds nothing.

type NullableInference

type NullableInference struct {
	// Disabled turns the wider reading off: a null then admits only what the
	// document's version says it does, and `nullable` in a schema read as JSON
	// Schema 2020-12 is a keyword that dialect does not define.
	Disabled bool `json:"disabled,omitzero"`
}

NullableInference is the nullable-inference policy: whether a null a schema spells widens what it is written on rather than conjoining with it, so that `nullable: true` admits null for its whole schema wherever it is written, and keywords beside a $ref that admit null admit it for the whole reference.

It is a policy because the wider reading guesses at intent (architecture principle 6): OpenAPI 3.0 makes `nullable` a member of the `type` beside it, 3.1 removed it, and JSON Schema conjoins a $ref with its siblings, yet documents written to 3.0.0's wording, or carried to 3.1, mean null is sent.

func (NullableInference) Honours

func (p NullableInference) Honours() bool

Honours reports whether the policy is on, so that a null a schema spells widens what it is written on.

type PageStatement

type PageStatement struct {
	// Expression is the runtime expression the source's value spells, empty
	// for a source that marks.
	Expression string
	// At is where the source's value is written, which a report names.
	At ir.Provenance
	// Stated reports whether the source says anything on the node: an
	// expression, or that the node is the value its target names.
	Stated bool
	// Written reports whether the source's key is on the node at all,
	// whatever its value: where it is, the document has spoken of the walk,
	// whether its value states a value, fails to or states nothing.
	Written bool
}

PageStatement is what one source of a pagination target says on one node.

func PageStatementOf

func PageStatementOf(p Promoter, target ExtensionTarget, src ExtensionSource, unmodeled, root ir.Unmodeled) (PageStatement, []ir.Diagnostic)

PageStatementOf reads what src, a source p reads the pagination target target from, says on the node keeping unmodeled (docs/compilers/openapi.md#extension-pagination): the expression its value spells where it lists no Values, and whether its value is one of them where it does. The key written false says nothing is there to read. Any other value stating nothing to every pagination source of the key is reported, worded alike for each, so one report stands per node. root is the document root's Unmodeled where the node is an operation, and nil otherwise, as an operation's true reads the root's (rootStatement).

type PaginationInference

type PaginationInference struct {
	// Disabled turns the reading off: no operation then carries a Pagination
	// the document does not declare.
	Disabled bool `json:"disabled,omitzero"`
}

PaginationInference is the pagination-inference policy: whether an operation's pagination is read off the names of its query parameters and of the members of its success responses (docs/compilers/openapi.md#pagination-policy).

It is a policy because the reading guesses at intent (architecture principle 6): OpenAPI has no keyword for pagination, so a paginated operation says so only by naming a parameter `page` or `cursor` and a member `result`, which promises nothing about how the API walks its pages.

func (PaginationInference) Honours

func (p PaginationInference) Honours() bool

Honours reports whether the policy is on, so that an operation's pagination is read off the names it uses.

type Policy

type Policy struct {
	Grouping               GroupingStrategy
	GroupingExtension      GroupingExtension
	Limits                 Limits
	StreamingInference     StreamingInference
	BinaryInference        BinaryInference
	Promotions             ExtensionPromotions
	NullableInference      NullableInference
	DiscriminatorInference DiscriminatorInference
	IdempotencyInference   IdempotencyInference
	SecretInference        SecretInference
	HTTPDateInference      HTTPDateInference
	ReplacementInference   ReplacementInference
	PaginationInference    PaginationInference
	TitleNames             TitleNames
}

Policy is the caller's choice of how a source is lowered, as the compiler's Options resolve it.

type Promoter

type Promoter struct {
	// contains filtered or unexported fields
}

Promoter reads preserved vendor extensions into typed fields, by a policy fixed when it is built. Its zero value is the disabled policy, and reads nothing. A reader of one target, such as ServerName, is a function over its Sources.

Every read takes the node's Unmodeled entries rather than the source node, which is what makes "the extension survives its own promotion" structural instead of a rule each caller has to remember: nothing here can consume an entry. It takes them at the top level, so a key under a scope or inside a verbatim entry reaches no field (GitHub #1220, #1221).

func (Promoter) Deprecation

func (p Promoter) Deprecation(own ir.Unmodeled, from Referent, dep **ir.Deprecation, prov *ir.Provenance) []ir.Diagnostic

Deprecation reads the extensions in own, and what from lends, into a deprecation: a key stating one creates *dep where no keyword did, then the members fill what is there, or what they write where from is deprecated and the node writes none (Referent.Homes). It marks prov with the heuristic when it writes anything.

A *dep still nil is the whole answer for a node that is not deprecated: a member beside none annotates nothing and stays where it is. A `deprecated: false` states nothing, so it stops no key (annotation.EffectiveDeprecated).

func (Promoter) Keys

func (p Promoter) Keys() iter.Seq[string]

Keys yields every extension key the policy reads, for a carrier to find on its referent.

func (Promoter) Lent

func (p Promoter) Lent(from Referent, own ir.Unmodeled, scopes ...string) Referent

Lent returns from with what the objects own carries state, each read as a $ref target's keys are: a single-sided fact holds where any states it, and a deprecation's members fill from the nearest stating them. The carrier's own keys are its caller's to read, and from is farther than any scope.

func (Promoter) Maps

func (p Promoter) Maps(target ExtensionTarget) bool

Maps reports whether the policy names any source for target.

func (Promoter) Redaction

func (p Promoter) Redaction(own ir.Unmodeled, from Referent, redact *bool, prov *ir.Provenance) []ir.Diagnostic

Redaction sets redact from the vendor extensions kept in own, or what from lends, and marks prov with the heuristic when that writes it. A redaction already asked for by `format: password` needs no guess, so it stays unmarked.

func (Promoter) Referent

func (p Promoter) Referent(of any, declared bool, entries func() ir.Unmodeled) Referent

Referent returns what a schema lends a carrier falling back to it. of names the schema, comparable and the same for each carrier, declared is its `deprecated: true`, and entries reads its mapped keys in Unmodeled's form, once for every copy of p: a schema has as many carriers as a document names it, and a key's value can be as large as the document.

The readings' findings are dropped because the schema is a declaration, and reports where it is written; a use repeating them would be one report per use.

func (Promoter) Replacements

func (p Promoter) Replacements(own ir.Unmodeled) ([]string, ir.Provenance, []ir.Diagnostic)

Replacements reads from own the names its node's replacements go by (TargetDeprecationReplacedBy), with the provenance of the key stating them, where a name that names nothing is reported. A string is one name and a list of strings several; another value is a misfit, reported as every target reports one. Nothing is read from a referent: a replacement names an entity of its own node's class, which a carrier and the type it uses are not.

func (Promoter) Sources

func (p Promoter) Sources(target ExtensionTarget) []ExtensionSource

Sources returns what the policy reads target from, in order of precedence. The list is the policy's own: a caller reads it and writes nothing to it.

func (Promoter) StatementOf

func (p Promoter) StatementOf(target ExtensionTarget, own ir.Unmodeled) (RawStatement, bool, []ir.Diagnostic)

StatementOf returns the value the first of p's sources of target writes on the node keeping own, read whole, and false where none writes one, for a step reading it once the document is whole (firstValue).

func (Promoter) TextOf

func (p Promoter) TextOf(target ExtensionTarget, unmodeled ir.Unmodeled) (TextStatement, []ir.Diagnostic)

TextOf reads what p's sources of target state on the node keeping unmodeled: the text of the first to state one, by the policy's order (firstValue). A value that is no text or an empty text states nothing, and is reported at its own key.

func (Promoter) Writes

func (p Promoter) Writes(own ir.Unmodeled, target ExtensionTarget) bool

Writes reports whether own keeps a key the policy reads target from, whatever its value says: a document writing one has spoken to the target, which a reading of its names then leaves alone.

type RawStatement

type RawStatement struct {
	Value  ir.RawValue
	Source ExtensionSource
	At     ir.Provenance
}

RawStatement is the value one source of a target writes on a node, read whole: what it holds, which source wrote it, and where.

type Referent

type Referent struct {
	// Deprecated reports that a key on the referent states it deprecated.
	Deprecated bool
	// Members is what the referent's keys state of its deprecation, empty on a
	// referent no keyword or key deprecates: there a member annotates nothing, so
	// it lends nothing, and a use's own `deprecated` gives it no home. An emitter
	// folding a decorator merges the Deprecation the node holds, and the two
	// spellings of one use have to agree (docs/emitters/refine/decorators.md).
	Members ir.Deprecation
	// Redacted reports that a key on the referent asks for redaction.
	Redacted bool
	// Homes reports that a schema the node falls back to is deprecated, by its
	// keyword or a key, so the node is deprecated through it though the node's
	// own Deprecation is unset, as a decorator's is, and a member the node
	// writes annotates that deprecation. Its caller sets it, as the keyword is
	// no key and the schema is not the node.
	Homes bool
}

Referent is what a carrier of a $ref reads of the schema the $ref ends on. Annotations merge from there field by field, a key on the carrier winning (docs/compilers/openapi.md#ref-use-site). The zero value is a carrier with no $ref, which is every carrier but a property, a header and a parameter.

type Repeat

type Repeat struct{ At, First int }

Repeat is an entry of a list written again: the entry at At repeats the one at First, its first occurrence.

func FirstOccurrences

func FirstOccurrences(entries []string) (kept []string, repeats []Repeat)

FirstOccurrences returns entries with each kept at its first occurrence, in the order written, and every repeat with the index it repeats, in order. Entries compare as the text written. A list repeating nothing is returned as it is, with no repeat, and one of at most pairwiseEntries allocates nothing.

type ReplacementInference

type ReplacementInference struct {
	// Disabled turns the reading off: a replacement the message names then
	// stays in the message alone.
	Disabled bool `json:"disabled,omitzero"`
}

ReplacementInference is the replacement policy: whether a deprecation whose message names what to use instead, in a form the document's own entities resolve, names it in ReplacedBy too, where no extension does.

It is a policy because the reading guesses at intent (architecture principle 6): a message is prose, and an entity it names need not be the replacement.

func (ReplacementInference) Honours

func (p ReplacementInference) Honours() bool

Honours reports whether the policy is on, so that a message's replacements fill ReplacedBy.

type SecretInference

type SecretInference struct {
	// Disabled turns the reading off: a value is then redacted only where the
	// document asks for it.
	Disabled bool `json:"disabled,omitzero"`
}

SecretInference is the secret policy: whether a parameter, a header or a property whose name says it holds a credential, and whose value is text, is redacted where the document asks for no redaction.

It is a policy because the reading guesses at intent (architecture principle 6): a name is no declaration, though a credential the document leaves unmarked is printed wherever its value is.

func (SecretInference) Honours

func (p SecretInference) Honours() bool

Honours reports whether the policy is on, so that a credential's name asks for its redaction.

type StreamingInference

type StreamingInference struct {
	// Disabled turns the inference off. Off means off: an operation then carries
	// the streaming fields a 3.2 itemSchema declares and nothing else, which is
	// what a caller who does not want guesses in their IR asked for.
	Disabled bool `json:"disabled,omitzero"`
	// MediaTypes replaces the default list rather than extending it, so a caller
	// who states a list gets exactly that list. Empty means the default.
	//
	// Entries are matched against the media type alone: the comparison is
	// case-insensitive and ignores parameters, because `text/event-stream` and
	// `text/event-stream; charset=utf-8` name one type. An entry starting with
	// `+` names a structured suffix, and matches every media type ending in it.
	MediaTypes []string `json:"mediaTypes,omitempty"`
}

StreamingInference is the media-type streaming policy: which media types mean "this body is a sequence of frames" in a document that declares nothing saying so.

It is a policy rather than a table in the lowering because the reading is a guess (architecture principle 6). OpenAPI below 3.2 has no keyword for a sequential body, so an SSE or NDJSON API says what it does only by naming a media type, which is a content encoding, not a promise about framing. The vocabulary is declared here, below both walks, and re-exported by the compiler's public options, as GroupingStrategy is.

type TextStatement

type TextStatement struct {
	// Text is what the first source stating a text states; empty where none
	// does.
	Text string
	// Source is the source Text is read from, unset with it.
	Source ExtensionSource
	// At is where Source's value sits, which a report names.
	At ir.Provenance
}

TextStatement is what the sources of one target state on one node, as text.

type TitleNames

type TitleNames struct {
	// Disabled turns the reading off: every anonymous node is named by its
	// position, its title kept as its summary alone.
	Disabled bool `json:"disabled,omitzero"`
}

TitleNames is the title-names policy: whether a schema's title names the anonymous node built from it, in place of the hint composed from its position (docs/compilers/openapi.md#naming).

It is a policy because JSON Schema declares a title a label for display, so preferring it over the position is a reading (architecture principle 6): a sentence written as a title names a node by every word, and editing one renames the node. It is unmarked in Provenance.Inferred, as a Hint with no Source is the suggestion already.

func (TitleNames) Honours

func (p TitleNames) Honours() bool

Honours reports whether the policy is on, so that a title names its node.

Directories

Path Synopsis
Package loweringtest builds the lowering context the compiler's tests lower under, over a document the load phase read, as the compiler builds its own.
Package loweringtest builds the lowering context the compiler's tests lower under, over a document the load phase read, as the compiler builds its own.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL