internal

Documentation

Index

• func AllCategoriesForVersionSpec(versionSpec *VersionSpec) []string
• func AllIDsForVersionSpec(versionSpec *VersionSpec, includeDeprecated bool) ([]string, error)
• func RelevantDeprecationsForVersionSpec(versionSpec *VersionSpec) (map[string][]string, error)
• type CheckFunc
• type Config
• type ConfigBuilder
  • func (b ConfigBuilder) NewConfig(versionSpec *VersionSpec, transformDeprecated bool) (*Config, error)
• type Helper
  • func NewHelper(id string, ignoreFunc IgnoreFunc) *Helper
  • func (h *Helper) AddFileAnnotationWithExtraIgnoreDescriptorsf(descriptor bufprotosource.Descriptor, ...)
  • func (h *Helper) AddFileAnnotationWithExtraIgnoreLocationsf(descriptor bufprotosource.Descriptor, location bufprotosource.Location, ...)
  • func (h *Helper) AddFileAnnotationf(descriptor bufprotosource.Descriptor, location bufprotosource.Location, ...)
  • func (h *Helper) FileAnnotations() []bufanalysis.FileAnnotation
• type IgnoreFunc
• type Rule
  • func (c *Rule) Categories() []string
  • func (c *Rule) Deprecated() bool
  • func (c *Rule) ID() string
  • func (c *Rule) Purpose() string
  • func (c *Rule) ReplacementIDs() []string
• type RuleBuilder
  • func NewDeprecatedRuleBuilder(id string, purpose string, replacementIDs []string) *RuleBuilder
  • func NewNopRuleBuilder(id string, purpose string, checkFunc CheckFunc) *RuleBuilder
  • func NewRuleBuilder(id string, purpose string, newCheck func(ConfigBuilder) (CheckFunc, error)) *RuleBuilder
  • func (c *RuleBuilder) Deprecated() bool
  • func (c *RuleBuilder) ID() string
  • func (c *RuleBuilder) NewRule(configBuilder ConfigBuilder, categories []string) (*Rule, error)
  • func (c *RuleBuilder) ReplacementIDs() []string
• type Runner
  • func NewRunner(logger *zap.Logger, tracer tracing.Tracer, options ...RunnerOption) *Runner
  • func (r *Runner) Check(ctx context.Context, config *Config, previousFiles []bufprotosource.File, ...) (retErr error)
• type RunnerOption
  • func RunnerWithIgnorePrefix(ignorePrefix string) RunnerOption
• type VersionSpec

Functions

func AllCategoriesForVersionSpec

func AllCategoriesForVersionSpec(versionSpec *VersionSpec) []string

AllCategoriesForVersionSpec returns all categories for the VersionSpec.

Sorted by category priority.

func AllIDsForVersionSpec

func AllIDsForVersionSpec(versionSpec *VersionSpec, includeDeprecated bool) ([]string, error)

AllIDsForVersionSpec returns all ids for the VersionSpec.

Sorted lexographically.

func RelevantDeprecationsForVersionSpec

func RelevantDeprecationsForVersionSpec(versionSpec *VersionSpec) (map[string][]string, error)

RelevantDeprecationsForVersionSpec returns the map of deprecations for the VersionSpec. The keys are deprecated rule names and the values are rules' replacements (which may be empty).

Types

type CheckFunc

type CheckFunc func(id string, ignoreFunc IgnoreFunc, previousFiles []bufprotosource.File, files []bufprotosource.File) ([]bufanalysis.FileAnnotation, error)

CheckFunc is a check function.

type Config

type Config struct {
	// Rules are the rules to run.
	//
	// Rules will be sorted by first categories, then id when Configs are
	// created from this package, i.e. created wth ConfigBuilder.NewConfig.
	Rules []*Rule

	IgnoreRootPaths     map[string]struct{}
	IgnoreIDToRootPaths map[string]map[string]struct{}

	AllowCommentIgnores    bool
	IgnoreUnstablePackages bool
}

Config is the check config.

This should only be built via a ConfigBuilder. If we were exposing this API publicly, we would enforce this.

type ConfigBuilder

type ConfigBuilder struct {
	// May contain deprecated IDs.
	Use []string
	// May contain deprecated IDs.
	Except []string

	IgnoreRootPaths []string
	// May contain deprecated IDs.
	IgnoreIDOrCategoryToRootPaths map[string][]string

	AllowCommentIgnores    bool
	IgnoreUnstablePackages bool

	EnumZeroValueSuffix                  string
	RPCAllowSameRequestResponse          bool
	RPCAllowGoogleProtobufEmptyRequests  bool
	RPCAllowGoogleProtobufEmptyResponses bool
	ServiceSuffix                        string
}

ConfigBuilder is a config builder.

func (ConfigBuilder) NewConfig

func (b ConfigBuilder) NewConfig(versionSpec *VersionSpec, transformDeprecated bool) (*Config, error)

NewConfig returns a new Config.

TransformDeprecated should always be true if building a Config for a Runner.

type Helper

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

Helper is a helper for rules.

func NewHelper

func NewHelper(id string, ignoreFunc IgnoreFunc) *Helper

NewHelper returns a new Helper for the given id.

func (*Helper) AddFileAnnotationWithExtraIgnoreDescriptorsf

func (h *Helper) AddFileAnnotationWithExtraIgnoreDescriptorsf(
	descriptor bufprotosource.Descriptor,
	extraIgnoreDescriptors []bufprotosource.Descriptor,
	location bufprotosource.Location,
	format string,
	args ...interface{},
)

AddFileAnnotationWithExtraIgnoreDescriptorsf adds a FileAnnotation with the id as the Type.

extraIgnoreDescriptors are extra desciptors to check for ignores.

If descriptor is nil, no filename information is added. If location is nil, no line or column information will be added.

func (*Helper) AddFileAnnotationWithExtraIgnoreLocationsf

func (h *Helper) AddFileAnnotationWithExtraIgnoreLocationsf(
	descriptor bufprotosource.Descriptor,
	location bufprotosource.Location,
	extraIgnoreLocations []bufprotosource.Location,
	format string,
	args ...interface{},
)

AddFileAnnotationWithExtraIgnoreLocationsf adds a FileAnnotation with the id as the Type.

extraIgnoreLocations are extra locations to check for comment ignores.

If descriptor is nil, no filename information is added. If location is nil, no line or column information will be added.

func (*Helper) AddFileAnnotationf

func (h *Helper) AddFileAnnotationf(
	descriptor bufprotosource.Descriptor,
	location bufprotosource.Location,
	format string,
	args ...interface{},
)

AddFileAnnotationf adds a FileAnnotation with the id as the Type.

If descriptor is nil, no filename information is added. If location is nil, no line or column information will be added.

func (*Helper) FileAnnotations

func (h *Helper) FileAnnotations() []bufanalysis.FileAnnotation

FileAnnotations returns the added FileAnnotations.

type IgnoreFunc

type IgnoreFunc func(id string, descriptors []bufprotosource.Descriptor, locations []bufprotosource.Location) bool

IgnoreFunc is an ignore function.

Descriptors are the descriptors to check for ignores. Sometimes we have multiple descriptors, such as when we want to check previous file descriptors, or if an entire package is deleted.

Locations are the locations to check for comment ignores. Sometimes, we have multiple locations to check, for example with RPC_REQUEST_STANDARD_NAME and RPC_RESPONSE_STANDARD_NAME, we want to check both the input/output type, and the method.

Any descriptor or location may be nil.

type Rule

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

Rule provides a base embeddable rule.

func (*Rule) Categories

func (c *Rule) Categories() []string

Categories implements Rule.

func (*Rule) Deprecated

func (c *Rule) Deprecated() bool

func (*Rule) ID

func (c *Rule) ID() string

ID implements Rule.

func (*Rule) Purpose

func (c *Rule) Purpose() string

Purpose implements Rule.

func (*Rule) ReplacementIDs

func (c *Rule) ReplacementIDs() []string

type RuleBuilder

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

RuleBuilder is a rule builder.

func NewDeprecatedRuleBuilder

func NewDeprecatedRuleBuilder(
	id string,
	purpose string,
	replacementIDs []string,
) *RuleBuilder

NewDeprecatedRuleBuilder returns a new RuleBuilder for a deprecated Rule.

replacementIDs may be nil or empty.

func NewNopRuleBuilder

func NewNopRuleBuilder(
	id string,
	purpose string,
	checkFunc CheckFunc,
) *RuleBuilder

NewNopRuleBuilder returns a new undeprecated RuleBuilder for the direct purpose and CheckFunc.

func NewRuleBuilder

func NewRuleBuilder(
	id string,
	purpose string,
	newCheck func(ConfigBuilder) (CheckFunc, error),
) *RuleBuilder

NewRuleBuilder returns a new undeprecated RuleBuilder.

func (*RuleBuilder) Deprecated

func (c *RuleBuilder) Deprecated() bool

Deprecated returns whether or not the Rule was deprecated.

func (*RuleBuilder) ID

func (c *RuleBuilder) ID() string

ID returns the id.

func (*RuleBuilder) NewRule

func (c *RuleBuilder) NewRule(configBuilder ConfigBuilder, categories []string) (*Rule, error)

NewRule returns a new Rule.

Categories will be sorted and Purpose will be prepended with "Checks that " and appended with ".".

Categories is an actual copy from the ruleBuilder.

func (*RuleBuilder) ReplacementIDs

func (c *RuleBuilder) ReplacementIDs() []string

ReplacementIDs returns the replacement IDs.

type Runner

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

Runner is a runner.

func NewRunner

func NewRunner(logger *zap.Logger, tracer tracing.Tracer, options ...RunnerOption) *Runner

NewRunner returns a new Runner.

func (*Runner) Check

func (r *Runner) Check(ctx context.Context, config *Config, previousFiles []bufprotosource.File, files []bufprotosource.File) (retErr error)

Check runs the Rules.

An error of type bufanalysis.FileAnnotationSet will be returned on a rule failure.

type RunnerOption

type RunnerOption func(*Runner)

RunnerOption is an option for a new Runner.

func RunnerWithIgnorePrefix

func RunnerWithIgnorePrefix(ignorePrefix string) RunnerOption

RunnerWithIgnorePrefix returns a new RunnerOption that sets the comment ignore prefix.

This will result in failures where the location has "ignore_prefix id" in the leading comment being ignored.

The default is to not enable comment ignores.

type VersionSpec

type VersionSpec struct {
	FileVersion       bufconfig.FileVersion
	RuleBuilders      []*RuleBuilder
	DefaultCategories []string
	// May include IDs without any categories.
	// To get all categories, use AllCategoriesForVersionSpec.
	IDToCategories map[string][]string
}

VersionSpec specifies the rules, ids, and categories for a given version.