compilers

type Compiler interface {
	Formats() []SourceFormat
	// Detect reports the format src declares, and whether this compiler
	// recognizes it at all. Recognition is not support: a compiler may name a
	// format it does not serve — a version it has yet to implement — so that the
	// caller can say so rather than report the source as unrecognized.
	//
	// An ok answer must name a format. Recognizing a source is knowing what it
	// is, so the zero format with ok true is no answer, and Registry.Detect
	// passes over a compiler that gives one rather than let it end the search.
	//
	// opts is what this compiler would compile src with, so that recognizing a
	// source is held to the bounds the caller set for reading it rather than to
	// a ceiling of the compiler's choosing: the read that recognition makes may
	// be the most expensive read of the source there is. A FormatOptions value
	// of a type this compiler does not take configures some other compiler, and
	// here means this one's defaults; Compile is where such a value is an error,
	// since only there is it certain the caller meant it for this compiler.
	//
	// A compiler that parsed src to recognize it may return that parse in
	// Recognition.Parsed, and read it back from Source.Parsed in Compile. It is
	// an optimization and never a protocol: a compiler must compile a source
	// whose Parsed is nil or another compiler's, since a caller calling Compile
	// directly never went through Detect at all.
	//
	// diags is what this compiler can say about a source it declines, and is read
	// only when ok is false. Bytes of another format are ordinary input here, so
	// declining them is silent: a compiler that reported every source it did not
	// take would bury the one report that matters under one per registered
	// format. It is for the narrower cases where the source is recognizably this
	// compiler's own and cannot be read — a malformed document in its own
	// serialization — or where opts forbid reading it at all, a source past the
	// caller's size budget. No other compiler is in a position to say either,
	// and the caller would otherwise have to report the source as unrecognized.
	Detect(src Source, opts Options) (rec Recognition, diags []ir.Diagnostic, ok bool)
	// DecodeOptions turns textual settings into the value this compiler expects
	// in Options.FormatOptions. An empty set yields defaults. An unknown key, an
	// unusable value, or a file that cannot be read is an error — a setting that
	// is silently ignored leaves the caller believing they configured something.
	DecodeOptions(set OptionSet) (any, error)
	Compile(ctx context.Context, sources []Source, opts Options) (*ir.Document, []ir.Diagnostic, error)
}

type Configure func(c Compiler) (Options, error)

type Detection struct {
	// Compiler is the compiler registered for the format the source was
	// recognized as, or nil when none is.
	Compiler Compiler
	// Recognition is what recognizing the source found. Its Format is the zero
	// format when nothing recognized it; see Registry.Detect.
	Recognition Recognition
	// Options is what Compiler compiles the source with: the answer Configure
	// gave for it, which the caller hands on rather than resolving again.
	Options Options
	// Declined collects what the compilers that declined the source had to say,
	// in the order they were asked, and is meaningful only when none took it.
	Declined []ir.Diagnostic
}

type OptionSet struct {
	// Settings maps an option name to its textual value. A nil or empty map asks
	// for defaults.
	Settings map[string]string
	// ReadFile loads a file a setting names, e.g. an overlay document. A
	// compiler does no file I/O of its own — Source is the whole of its input,
	// which is what keeps compilation pure and reentrant — so the caller supplies
	// the reader and the read stays the caller's. A nil ReadFile means no setting
	// may name a file.
	ReadFile func(name string) ([]byte, error)
}

type Options struct {
	FormatOptions any
}

type Recognition struct {
	// Format is the dialect the source declares. An ok recognition names one.
	Format SourceFormat
	// Parsed is the value to put in Source.Parsed before compiling this source,
	// or nil when the compiler parsed nothing worth keeping — it read the bytes
	// some other way, or it declined.
	Parsed any
}

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

type Source struct {
	Path string
	Data []byte
	// Parsed is what a compiler's own Detect already made of Data, for its
	// Compile to use instead of reading the bytes a second time. Recognizing a
	// source and lowering it both begin by parsing it, and the two calls are
	// back to back over the same bytes, so without this every compile parses
	// its input twice.
	//
	// It is never required. A nil Parsed — what a caller assembling a Source by
	// hand leaves — means the compiler parses Data itself, and so does a value
	// of a type it does not recognize, which is the only thing it may assume
	// about one: the type is the producing compiler's own, and a compiler must
	// type-assert with comma-ok rather than trust what it is handed.
	//
	// A Parsed value belongs to one Compile. What a compiler leaves here is live
	// state it writes through while compiling, so a Source carrying one may not
	// be compiled twice or shared between concurrent Compile calls. Data may
	// change under it, on the other hand, and a compiler must notice: bytes that
	// no longer match the parse beside them are read afresh rather than lowered
	// from a tree that does not describe them. Registry.Detect produces one per
	// source, and drops it unless the compiler that produced it is the one that
	// will consume it.
	Parsed any
}

type SourceFormat struct {
	Name    string // "openapi", "swagger", "typespec", "smithy", ...
	Version string // "3.0", "3.1", "2.0", ...
}