libasyncapi

type CircularReferenceError struct {
	Path  string
	Chain []string
}

type Document interface {
	// GetVersion will return the exact version of the AsyncAPI specification set for the document.
	GetVersion() string

	// GetSpecInfo will return the SpecInfo instance that contains all specification information.
	GetSpecInfo() *SpecInfo

	// Model returns the high-level AsyncAPI model.
	// Returns nil if parsing completely failed.
	Model() *highasync.AsyncAPI

	// GoLow returns the low-level AsyncAPI model.
	// This provides access to line/column numbers and raw YAML nodes.
	GoLow() *lowasync.AsyncAPI

	// Index returns the reference index for this document.
	Index() *index.SpecIndex

	// Rolodex returns the file management system for multi-file specs.
	Rolodex() *index.Rolodex

	// RootNode returns the original YAML tree (not normalized).
	// This provides raw access for tooling that needs the original structure.
	RootNode() *yaml.Node

	// Serialize marshals the original YAML root node back to bytes.
	// This preserves the original structure and formatting.
	// For model-based rendering, use Render() instead.
	Serialize() ([]byte, error)

	// Render will return a YAML representation of the high-level model.
	Render() ([]byte, error)

	// Errors returns all errors accumulated during parsing.
	// The document may still contain a partial model even if errors occurred.
	Errors() []error

	// IsPartial returns true if errors occurred during parsing.
	// When true, the model may be incomplete but still usable.
	IsPartial() bool
}

type DocumentConfiguration struct {
	// BasePath is the base path for resolving relative file references.
	// If empty, the current working directory is used.
	BasePath string

	// BaseURL is the base URL for resolving relative URL references.
	BaseURL *url.URL

	// AllowFileReferences enables resolution of file:// references.
	// Defaults to false.
	AllowFileReferences bool

	// AllowRemoteReferences enables resolution of http:// and https:// references.
	// Defaults to false.
	AllowRemoteReferences bool

	// RemoteURLHandler is a custom function for fetching remote references.
	// If nil, the default http client is used.
	RemoteURLHandler func(url string) (*http.Response, error)

	// LocalFS is a custom filesystem for resolving local file references.
	// If nil, the OS filesystem is used.
	LocalFS fs.FS

	// SkipCircularReferenceCheck disables circular reference detection.
	// This can improve performance but may cause infinite loops if circular
	// references exist in the specification.
	SkipCircularReferenceCheck bool

	// ExtractRefsSequentially processes references one at a time instead of
	// in parallel. This is slower but can be useful for debugging.
	ExtractRefsSequentially bool

	// Logger is an optional structured logger for diagnostic messages.
	Logger *slog.Logger
}

type ParseError struct {
	Message string
	Line    int
	Column  int
	Path    string
}

type ReferenceError struct {
	Reference string
	Message   string
	Line      int
	Column    int
}

type SpecInfo struct {
	Version       string
	VersionParsed *semver.Version
	SpecType      string
}

type ValidationError struct {
	Message string
	Path    string
}