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
	// Location is the location of the failure.
	Location() Location
	// AgainstLocation is the Location of the failure in the against Files.
	//
	// Will only potentially be produced for breaking change rules.
	AgainstLocation() Location
	// 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 {
	// 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 File interface {
	// FileDescriptor returns the protoreflect FileDescriptor representing this File.
	//
	// This will always contain SourceCodeInfo.
	FileDescriptor() protoreflect.FileDescriptor
	// FileDescriptorProto returns the FileDescriptorProto representing this File.
	//
	// This is not a copy - do not modify!
	FileDescriptorProto() *descriptorpb.FileDescriptorProto
	// IsImport returns true if the File is an import.
	//
	// An import is a file that is either:
	//
	//   - A Well-Known Type included from the compiler and imported by a targeted file.
	//   - A file that was included from a Buf module dependency and imported by a targeted file.
	//   - A file that was not targeted, but was imported by a targeted file.
	//
	// We use "import" as this matches with the protoc concept of --include_imports, however
	// import is a bit of an overloaded term.
	IsImport() bool

	// IsSyntaxUnspecified denotes whether the file did not have a syntax explicitly specified.
	//
	// Per the FileDescriptorProto spec, it would be fine in this case to just leave the syntax field
	// unset to denote this and to set the syntax field to "proto2" if it is specified. However,
	// protoc does not set the syntax field if it was "proto2". Plugins may want to differentiate
	// between "proto2" and unset, and this field allows them to.
	IsSyntaxUnspecified() bool

	// UnusedDependencyIndexes are the indexes within the Dependency field on FileDescriptorProto for
	// those dependencies that are not used.
	//
	// This matches the shape of the PublicDependency and WeakDependency fields.
	UnusedDependencyIndexes() []int32
	// contains filtered or unexported methods
}

type ListCategoriesCallOption func(*listCategoriesCallOptions)

type ListRulesCallOption func(*listRulesCallOptions)

type Location interface {
	// File is the File associated with the Location.
	//
	// Always present.
	File() File
	// SourcePath returns the path within the FileDescriptorProto of the Location.
	SourcePath() protoreflect.SourcePath

	// StartLine returns the zero-indexed start line, if known.
	StartLine() int
	// StartColumn returns the zero-indexed start column, if known.
	StartColumn() int
	// EndLine returns the zero-indexed end line, if known.
	EndLine() int
	// EndColumn returns the zero-indexed end column, if known.
	EndColumn() int
	// LeadingComments returns any leading comments, if known.
	LeadingComments() string
	// TrailingComments returns any trailing comments, if known.
	TrailingComments() string
	// LeadingDetachedComments returns any leading detached comments, if known.
	LeadingDetachedComments() []string
	// contains filtered or unexported methods
}

type MainOption func(*mainOptions)

type Options interface {
	// Get gets the option value for the given key.
	//
	// Values will be one of:
	//
	// - int64
	// - float64
	// - string
	// - []byte
	// - bool
	// - A slice of any of the above, recursively (i.e. []string, [][]int64, ...)
	//
	// A caller should not modify a returned value.
	//
	// The key must have at least four characters.
	// The key must start and end with a lowercase letter from a-z, and only consist
	// of lowercase letters from a-z and underscores.
	Get(key string) (any, bool)
	// Range ranges over all key/value pairs.
	//
	// The range order is not deterministic.
	Range(f func(key string, value any))
	// contains filtered or unexported methods
}

type Request interface {
	// Files contains the files to check.
	//
	// Will never be nil or empty.
	//
	// Files are guaranteed to be unique with respect to their file name
	Files() []File
	// AgainstFiles contains the files to check against, in the case of breaking change plugins.
	//
	// May be empty, including in the case where we did actually specify against files.
	//
	// Files are guaranteed to be unique with respect to their file name
	AgainstFiles() []File
	// Options contains any options passed to the plugin.
	//
	// Will never be nil, but may have no values.
	Options() 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 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

	// 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)
}