check

type AddAnnotationOption func(*addAnnotationOptions)

type Annotation interface {
	// RuleID is the ID of the Rule that failed.
	//
	// This will always be present.
	RuleID() string
	// Message is a user-readable message describing the failure.
	Message() string
	// FileLocation is the location of the failure.
	FileLocation() descriptor.FileLocation
	// AgainstFileLocation is the FileLocation of the failure in the against FileDescriptors.
	//
	// Will only potentially be produced for breaking change rules.
	AgainstFileLocation() descriptor.FileLocation
	// contains filtered or unexported methods
}

type Category interface {
	// ID is the ID of the Category.
	//
	// Always present.
	//
	// This uniquely identifies the Category.
	ID() string
	// A user-displayable purpose of the category.
	//
	// Always present.
	Purpose() string
	// Deprecated returns whether or not this Category is deprecated.
	//
	// If the Category is deprecated, it may be replaced by zero or more Categories. These will
	// be denoted by ReplacementIDs.
	Deprecated() bool
	// ReplacementIDs returns the IDs of the Categories that replace this Category, if this Category is deprecated.
	//
	// This means that the combination of the Categories specified by ReplacementIDs replace this Category entirely,
	// and this Category is considered equivalent to the AND of the categories specified by ReplacementIDs.
	//
	// This will only be non-empty if Deprecated is true.
	//
	// It is not valid for a deprecated Category to specfiy another deprecated Category as a replacement.
	ReplacementIDs() []string
	// contains filtered or unexported methods
}

type CategorySpec struct {
	// Required.
	ID string
	// Required.
	Purpose        string
	Deprecated     bool
	ReplacementIDs []string
}

type CheckCallOption func(*checkCallOptions)

type CheckServiceHandlerOption func(*checkServiceHandlerOptions)

type Client interface {
	info.Client

	// Check invokes a check using the plugin..
	Check(ctx context.Context, request Request, options ...CheckCallOption) (Response, error)
	// ListRules lists all available Rules from the plugin.
	//
	// The Rules will be sorted by Rule ID.
	// Returns error if duplicate Rule IDs were detected from the underlying source.
	ListRules(ctx context.Context, options ...ListRulesCallOption) ([]Rule, error)
	// ListCategories lists all available Categories from the plugin.
	//
	// The Categories will be sorted by Category ID.
	// Returns error if duplicate Category IDs were detected from the underlying source.
	ListCategories(ctx context.Context, options ...ListCategoriesCallOption) ([]Category, error)
	// contains filtered or unexported methods
}

type ClientForSpecOption interface {
	// contains filtered or unexported methods
}

type ClientOption interface {
	ClientForSpecOption
	// contains filtered or unexported methods
}

type ListCategoriesCallOption func(*listCategoriesCallOptions)

type ListRulesCallOption func(*listRulesCallOptions)

type MainOption func(*mainOptions)

type Request interface {
	// FileDescriptors contains the FileDescriptors to check.
	//
	// Will never be nil or empty.
	//
	// FileDescriptors are guaranteed to be unique with respect to their name.
	FileDescriptors() []descriptor.FileDescriptor
	// AgainstFileDescriptors contains the FileDescriptors to check against, in the
	// case of breaking change plugins.
	//
	// May be empty, including in the case where we did actually specify against
	// FileDescriptors.
	//
	// FileDescriptors are guaranteed to be unique with respect to their name.
	AgainstFileDescriptors() []descriptor.FileDescriptor
	// Options contains any options passed to the plugin.
	//
	// Will never be nil, but may have no values.
	Options() option.Options
	// RuleIDs returns the specific IDs the of Rules to use.
	//
	// If empty, all default Rules will be used.
	// The returned RuleIDs will be sorted.
	//
	// This may return more than 250 IDs; the underlying Client implemention is required to do
	// any necessary chunking.
	//
	// RuleHandlers can safely ignore this - the handling of RuleIDs will have already
	// been performed prior to the Request reaching the RuleHandler.
	RuleIDs() []string
	// contains filtered or unexported methods
}

type RequestOption func(*requestOptions)

type Response interface {
	// Annotations returns all of the Annotations.
	//
	// The returned annotations will be sorted.
	Annotations() []Annotation
	// contains filtered or unexported methods
}

type ResponseWriter interface {
	// AddAnnotation adds an Annotation with the rule ID that is tied to this ResponseWriter.
	//
	// Fields of the Annotation are controlled with AddAnnotationOptions, of which there are several:
	//
	//   - WithMessage/WithMessagef: Add a message to the Annotation.
	//   - WithDescriptor/WithAgainstDescriptor: Use the protoreflect.Descriptor to determine Location information.
	//   - WithFileName/WithAgainstFileName: Use the given file name on the Location.
	//   - WithFileNameAndSourcePath/WithAgainstFileNameAndSourcePath: Use the given explicit file name and source path on the Location.
	//
	// There are some rules to note when using AddAnnotationOptions:
	//
	//   - Multiple calls of WithMessage/WithMessagef will overwrite previous calls.
	//   - You must either use WithDescriptor, or use WithFileName/WithSourcePath, but you cannot
	//     use these together. Location information is determined either from the Descriptor, or
	//     from explicit setting via WithFileName/WithFileNameAndSourcePath. Same applies to the Against equivalents.
	//
	// Don't worry, these rules are verified when building a Response.
	//
	// Most users will use WithDescriptor/WithAgainstDescriptor as opposed to their lower-level variants.
	AddAnnotation(options ...AddAnnotationOption)
	// contains filtered or unexported methods
}

type Rule interface {
	// ID is the ID of the Rule.
	//
	// Always present.
	//
	// This uniquely identifies the Rule.
	ID() string
	// The categories that the Rule is a part of.
	//
	// Optional.
	//
	// Buf uses categories to include or exclude sets of rules via configuration.
	Categories() []Category
	// Whether or not the Rule is a default Rule.
	//
	// If a Rule is a default Rule, it will be called if a Request specifies no specific Rule IDs.
	//
	// A deprecated rule cannot be a default rule.
	Default() bool
	// A user-displayable purpose of the rule.
	//
	// Always present.
	//
	// This should be a proper sentence that starts with a capital letter and ends in a period.
	Purpose() string
	// Type is the type of the Rule.
	Type() RuleType
	// Deprecated returns whether or not this Rule is deprecated.
	//
	// If the Rule is deprecated, it may be replaced by 0 or more Rules. These will be denoted
	// by ReplacementIDs.
	Deprecated() bool
	// ReplacementIDs returns the IDs of the Rules that replace this Rule, if this Rule is deprecated.
	//
	// This means that the combination of the Rules specified by ReplacementIDs replace this Rule entirely,
	// and this Rule is considered equivalent to the AND of the rules specified by ReplacementIDs.
	//
	// This will only be non-empty if Deprecated is true.
	//
	// It is not valid for a deprecated Rule to specfiy another deprecated Rule as a replacement.
	ReplacementIDs() []string
	// contains filtered or unexported methods
}

type RuleHandler interface {
	Handle(ctx context.Context, responseWriter ResponseWriter, request Request) error
}

type RuleHandlerFunc func(context.Context, ResponseWriter, Request) error

type RuleSpec struct {
	// Required.
	ID          string
	CategoryIDs []string
	Default     bool
	// Required.
	Purpose string
	// Required.
	Type           RuleType
	Deprecated     bool
	ReplacementIDs []string
	// Required.
	Handler RuleHandler
}

type RuleType int

type ServerOption func(*serverOptions)

type Spec struct {
	// Required.
	//
	// All RuleSpecs must have Category IDs that match a CategorySpec within Categories.
	//
	// No IDs can overlap with Category IDs in Categories.
	Rules []*RuleSpec
	// Required if any RuleSpec specifies a category.
	//
	// All CategorySpecs must have an ID that matches at least one Category ID on a
	// RuleSpec within Rules.
	//
	// No IDs can overlap with Rule IDs in Rules.
	Categories []*CategorySpec

	// Info contains information about a plugin.
	//
	// Optional.
	//
	// If not set, the resulting server will not implement the PluginInfoService.
	Info *info.Spec

	// Before is a function that will be executed before any RuleHandlers are
	// invoked that returns a new Context and Request. This new Context and
	// Request will be passed to the RuleHandlers. This allows for any
	// pre-processing that needs to occur.
	Before func(ctx context.Context, request Request) (context.Context, Request, error)
}