bufcheck

Documentation

Index

• func GetDeprecatedIDToReplacementIDs[R RuleOrCategory](rulesOrCategories []R) (map[string][]string, error)
• func PrintRules(writer io.Writer, rules []Rule, options ...PrintRulesOption) (retErr error)
• type AllCategoriesOption
• type AllRulesOption
• type BreakingOption
  • func BreakingWithExcludeImports() BreakingOption
• type Category
• type Client
  • func NewClient(logger *slog.Logger, options ...ClientOption) (Client, error)
• type ClientFunctionOption
  • func WithPluginConfigs(pluginConfigs ...bufconfig.PluginConfig) ClientFunctionOption
  • func WithPolicyConfigs(policyConfigs ...bufconfig.PolicyConfig) ClientFunctionOption
• type ClientOption
  • func ClientWithLocalPolicies(readFile func(string) ([]byte, error)) ClientOption
  • func ClientWithLocalPoliciesFromOS() ClientOption
  • func ClientWithLocalWasmPlugins(readFile func(string) ([]byte, error)) ClientOption
  • func ClientWithLocalWasmPluginsFromOS() ClientOption
  • func ClientWithRemoteWasmPlugins(pluginKeyProvider bufplugin.PluginKeyProvider, ...) ClientOption
  • func ClientWithRunnerProvider(runnerProvider RunnerProvider) ClientOption
  • func ClientWithStderr(stderr io.Writer) ClientOption
• type ConfiguredRulesOption
• type LintBreakingAndConfiguredRulesOption
  • func WithRelatedCheckConfigs(relatedCheckConfigs ...bufconfig.CheckConfig) LintBreakingAndConfiguredRulesOption
• type LintOption
• type PrintRulesOption
  • func PrintRulesWithDeprecated() PrintRulesOption
  • func PrintRulesWithJSON() PrintRulesOption
• type Rule
• type RuleOrCategory
• type RunnerProvider
  • func NewLocalRunnerProvider(wasmRuntime wasm.Runtime) RunnerProvider
• type RunnerProviderFunc
  • func (r RunnerProviderFunc) NewRunner(plugin bufplugin.Plugin) (pluginrpc.Runner, error)

Functions

func GetDeprecatedIDToReplacementIDs

func GetDeprecatedIDToReplacementIDs[R RuleOrCategory](rulesOrCategories []R) (map[string][]string, error)

GetDeprecatedIDToReplacementIDs gets a map from deprecated ID to replacement IDs.

func PrintRules

func PrintRules(writer io.Writer, rules []Rule, options ...PrintRulesOption) (retErr error)

PrintRules prints the rules to the Writer.

Types

type AllCategoriesOption

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

AllCategoriesOption is an option for AllCategories.

type AllRulesOption

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

AllRulesOption is an option for AllRules.

type BreakingOption

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

BreakingOption is an option for Breaking.

func BreakingWithExcludeImports

func BreakingWithExcludeImports() BreakingOption

BreakingWithExcludeImports returns a new BreakingOption that says to exclude imports from breaking change detection.

The default is to check imports for breaking changes.

type Category

type Category interface {
	check.Category

	// PluginName returns the name of the plugin that created this Category.
	//
	// Names are freeform.
	//
	// Will be empty for Categorys based on builtin plugins.
	PluginName() string
	// contains filtered or unexported methods
}

Category is an individual line or breaking Category.

It wraps check.Category and adds the name of the plugin that implements the Category.

type Client

type Client interface {
	// Lint lints the given Image with the given LintConfig.
	//
	// The Image should have source code info for this to work properly.
	//
	// Images should *not* be filtered with regards to imports before passing to this function.
	//
	// An error of type bufanalysis.FileAnnotationSet will be returned lint failure.
	Lint(ctx context.Context, config bufconfig.LintConfig, image bufimage.Image, options ...LintOption) error
	// Breaking checks the given Images for breaking changes with the given BreakingConfig.
	//
	// The Images should have source code info for this to work properly.
	//
	// Images should *not* be filtered with regards to imports before passing to this function.
	// To exclude imports, pass BreakingWithExcludeImports.
	//
	// An error of type bufanalysis.FileAnnotationSet will be returned lint failure.
	Breaking(ctx context.Context, config bufconfig.BreakingConfig, image bufimage.Image, againstImage bufimage.Image, options ...BreakingOption) error
	// ConfiguredRules returns all of the Configured Rules for the given RuleType.
	ConfiguredRules(ctx context.Context, ruleType check.RuleType, config bufconfig.CheckConfig, options ...ConfiguredRulesOption) ([]Rule, error)
	// AllRules returns all Rules (configured or not) for the given RuleType.
	AllRules(ctx context.Context, ruleType check.RuleType, fileVersion bufconfig.FileVersion, options ...AllRulesOption) ([]Rule, error)
	// AllCategories returns all Categories.
	AllCategories(ctx context.Context, fileVersion bufconfig.FileVersion, options ...AllCategoriesOption) ([]Category, error)
}

Rules are returned sorted by ID, but PrintRules does our sort by category.

func NewClient

func NewClient(
	logger *slog.Logger,
	options ...ClientOption,
) (Client, error)

NewClient returns a new Client.

type ClientFunctionOption

type ClientFunctionOption interface {
	LintOption
	BreakingOption
	ConfiguredRulesOption
	AllRulesOption
	AllCategoriesOption
}

ClientFunctionOption is an option that applies to any Client function.

func WithPluginConfigs

func WithPluginConfigs(pluginConfigs ...bufconfig.PluginConfig) ClientFunctionOption

WithPluginConfigs returns a new ClientFunctionOption that says to also use the given plugins.

The default is to only use the builtin Rules and Categories.

func WithPolicyConfigs

func WithPolicyConfigs(policyConfigs ...bufconfig.PolicyConfig) ClientFunctionOption

WithPolicyConfigs returns a new ClientFunctionOption that says to also use the given policies.

type ClientOption

type ClientOption func(*clientOptions)

ClientOption is an option for a new Client.

func ClientWithLocalPolicies

func ClientWithLocalPolicies(readFile func(string) ([]byte, error)) ClientOption

ClientWithLocalPolicies returns a new ClientOption that specifies reading local policies.

The readFile is used to read the policy data from the filesystem.

func ClientWithLocalPoliciesFromOS

func ClientWithLocalPoliciesFromOS() ClientOption

ClientWithLocalPoliciesFromOS returns a new ClientOption that specifies reading local policies from the OS.

func ClientWithLocalWasmPlugins

func ClientWithLocalWasmPlugins(readFile func(string) ([]byte, error)) ClientOption

ClientWithLocalWasmPlugins returns a new ClientOption that specifies reading Wasm plugins.

The readFile is used to read the Wasm plugin data from the filesystem.

func ClientWithLocalWasmPluginsFromOS

func ClientWithLocalWasmPluginsFromOS() ClientOption

ClientWithLocalWasmPluginsFromOS returns a new ClientOption that specifies reading Wasm plugins from the OS.

This is only used for local applications.

func ClientWithRemoteWasmPlugins

func ClientWithRemoteWasmPlugins(
	pluginKeyProvider bufplugin.PluginKeyProvider,
	pluginDataProvider bufplugin.PluginDataProvider,
) ClientOption

ClientWithRemoteWasmPlugins returns a new ClientOption that specifies the remote plugin key and data providers.

func ClientWithRunnerProvider

func ClientWithRunnerProvider(runnerProvider RunnerProvider) ClientOption

ClientWithRunnerProvider returns a new ClientOption that specifies a RunnerProvider.

The runnerProvider is used to create pluginrpc.Runners for the plugins. By default, only builtin plugins are used.

func ClientWithStderr

func ClientWithStderr(stderr io.Writer) ClientOption

ClientWithStderr returns a new ClientOption that specifies a stderr to proxy plugin stderrs to.

The default is the equivalent of /dev/null.

type ConfiguredRulesOption

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

ConfiguredRulesOption is an option for ConfiguredRules.

type LintBreakingAndConfiguredRulesOption

type LintBreakingAndConfiguredRulesOption interface {
	LintOption
	BreakingOption
	ConfiguredRulesOption
}

LintBreakingAndConfiguredRulesOption is an option for Lint, Breaking, and ConfiguredRules.

func WithRelatedCheckConfigs

func WithRelatedCheckConfigs(relatedCheckConfigs ...bufconfig.CheckConfig) LintBreakingAndConfiguredRulesOption

WithRelatedCheckConfigs returns a new LintBreakingAndConfiguredRulesOption that allows the caller to provide additional related check configs. This allows the client to check for unused plugins across related check configs and provide users with a warning if the plugin is unused in all check configs.

The default is to only check the configs provided to the client for Lint, Breaking, or ConfiguredRules.

type LintOption

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

LintOption is an option for Lint.

type PrintRulesOption

type PrintRulesOption func(*printRulesOptions)

PrintRulesOption is an option for PrintRules.

func PrintRulesWithDeprecated

func PrintRulesWithDeprecated() PrintRulesOption

PrintRulesWithDeprecated returns a new PrintRulesOption that results in deprecated rules being printed.

func PrintRulesWithJSON

func PrintRulesWithJSON() PrintRulesOption

PrintRulesWithJSON returns a new PrintRulesOption that says to print the rules as JSON.

The default is to print as text.

type Rule

type Rule interface {
	check.Rule

	// BufcheckCategories returns the Rule's Categories.
	BufcheckCategories() []Category

	// PluginName returns the name of the plugin that created this Rule.
	//
	// Names are freeform.
	//
	// Will be empty for Rules based on builtin plugins.
	PluginName() string
	// contains filtered or unexported methods
}

Rule is an individual line or breaking Rule.

It wraps check.Rule and adds the name of the plugin that implements the Rule.

type RuleOrCategory

type RuleOrCategory interface {
	ID() string
	Purpose() string
	Deprecated() bool
	ReplacementIDs() []string
	PluginName() string
	// contains filtered or unexported methods
}

RuleOrCategory is a union interface with the common types in both Rule and Category.

type RunnerProvider

type RunnerProvider interface {
	NewRunner(plugin bufplugin.Plugin) (pluginrpc.Runner, error)
}

RunnerProvider provides pluginrpc.Runners for a given plugin config and an optional policy config.

func NewLocalRunnerProvider

func NewLocalRunnerProvider(wasmRuntime wasm.Runtime) RunnerProvider

NewLocalRunnerProvider returns a new RunnerProvider to invoke plugins locally.

This implementation should only be used for local applications. It is safe to use concurrently.

The RunnerProvider selects the correct Runner based on the Plugin:

• Local plugins will be run with pluginrpcutil.NewLocalRunner.
• Local Wasm plugins will be run with pluginrpcutil.NewWasmRunner.
• Remote Wasm plugins will be run with pluginrpcutil.NewWasmRunner.

If the plugin type is not supported, an error is returned. To disable support for Wasm plugins, set wasmRuntime to wasm.UnimplementedRuntime.

type RunnerProviderFunc

type RunnerProviderFunc func(bufplugin.Plugin) (pluginrpc.Runner, error)

RunnerProviderFunc is a function that implements RunnerProvider.

func (RunnerProviderFunc) NewRunner

func (r RunnerProviderFunc) NewRunner(plugin bufplugin.Plugin) (pluginrpc.Runner, error)

NewRunner implements RunnerProvider.

RunnerProvider selects the correct Runner based on the type of pluginConfig.