Add buf policy YAML file config (#3769)

Author: emcfarlane

private/buf/bufmigrate/migrator.go

@@ -380,7 +380,8 @@ func (m *migrator) buildBufYAMLAndBufLockFiles(
 		bufYAML, err := bufconfig.NewBufYAMLFile(
 			bufconfig.FileVersionV2,
 			migrateBuilder.moduleConfigs,
-			// TODO: If we ever need to migrate from a v2 to v3, we will need to handle PluginConfigs
+			// TODO: If we ever need to migrate from a v2 to v3, we will need to handle PluginConfigs and PolicyConfigs
+			nil,
 			nil,
 			resolvedDeclaredRefs,
 		)
@@ -429,7 +430,8 @@ func (m *migrator) buildBufYAMLAndBufLockFiles(
 	bufYAML, err := bufconfig.NewBufYAMLFile(
 		bufconfig.FileVersionV2,
 		migrateBuilder.moduleConfigs,
-		// TODO: If we ever need to migrate from a v2 to v3, we will need to handle PluginConfigs
+		// TODO: If we ever need to migrate from a v2 to v3, we will need to handle PluginConfigs and PolicyConfigs
+		nil,
 		nil,
 		resolvedDepModuleRefs,
 	)

private/buf/cmd/buf/command/config/configinit/configinit.go

@@ -175,6 +175,7 @@ func run(
 		},
 		nil,
 		nil,
+		nil,
 		bufconfig.BufYAMLFileWithIncludeDocsLink(),
 	)
 	if err != nil {

private/buf/cmd/buf/command/config/configlsmodules/configlsmodules.go

@@ -143,6 +143,7 @@ func getExternalModules(
 				},
 				nil,
 				nil,
+				nil,
 			)
 			if err != nil {
 				return nil, err

private/buf/cmd/buf/command/config/internal/internal.go

@@ -177,6 +177,7 @@ func lsRun(
 			},
 			nil,
 			nil,
+			nil,
 		)
 		if err != nil {
 			return err

private/buf/cmd/buf/command/mod/internal/internal.go

@@ -162,6 +162,7 @@ func lsRun(
 			},
 			nil,
 			nil,
+			nil,
 		)
 		if err != nil {
 			return err

private/bufpkg/bufconfig/buf_yaml_file.go

@@ -105,6 +105,10 @@ type BufYAMLFile interface {
 	//
 	// For v1 buf.yaml files, this will always return nil.
 	PluginConfigs() []PluginConfig
+	// PolicyConfigs returns the PolicyConfigs for the File.
+	//
+	// For v1 buf.yaml files, this will always return nil.
+	PolicyConfigs() []PolicyConfig
 	// ConfiguredDepModuleRefs returns the configured dependencies of the Workspace as ModuleRefs.
 	//
 	// These come from buf.yaml files.
@@ -126,6 +130,7 @@ func NewBufYAMLFile(
 	fileVersion FileVersion,
 	moduleConfigs []ModuleConfig,
 	pluginConfigs []PluginConfig,
+	policyConfigs []PolicyConfig,
 	configuredDepModuleRefs []bufparse.Ref,
 	options ...BufYAMLFileOption,
 ) (BufYAMLFile, error) {
@@ -140,6 +145,7 @@ func NewBufYAMLFile(
 		nil, // Do not set top-level lint config, use only module configs
 		nil, // Do not set top-level breaking config, use only module configs
 		pluginConfigs,
+		policyConfigs,
 		configuredDepModuleRefs,
 		bufYAMLFileOptions.includeDocsLink,
 	)
@@ -254,6 +260,7 @@ type bufYAMLFile struct {
 	topLevelLintConfig      LintConfig
 	topLevelBreakingConfig  BreakingConfig
 	pluginConfigs           []PluginConfig
+	policyConfigs           []PolicyConfig
 	configuredDepModuleRefs []bufparse.Ref
 	includeDocsLink         bool
 }
@@ -265,6 +272,7 @@ func newBufYAMLFile(
 	topLevelLintConfig LintConfig,
 	topLevelBreakingConfig BreakingConfig,
 	pluginConfigs []PluginConfig,
+	policyConfigs []PolicyConfig,
 	configuredDepModuleRefs []bufparse.Ref,
 	includeDocsLink bool,
 ) (*bufYAMLFile, error) {
@@ -320,6 +328,7 @@ func newBufYAMLFile(
 		topLevelLintConfig:      topLevelLintConfig,
 		topLevelBreakingConfig:  topLevelBreakingConfig,
 		pluginConfigs:           pluginConfigs,
+		policyConfigs:           policyConfigs,
 		configuredDepModuleRefs: configuredDepModuleRefs,
 		includeDocsLink:         includeDocsLink,
 	}, nil
@@ -353,6 +362,10 @@ func (c *bufYAMLFile) PluginConfigs() []PluginConfig {
 	return c.pluginConfigs
 }
 
+func (c *bufYAMLFile) PolicyConfigs() []PolicyConfig {
+	return c.policyConfigs
+}
+
 func (c *bufYAMLFile) ConfiguredDepModuleRefs() []bufparse.Ref {
 	return slices.Clone(c.configuredDepModuleRefs)
 }
@@ -455,6 +468,7 @@ func readBufYAMLFile(
 			lintConfig,
 			breakingConfig,
 			nil,
+			nil,
 			configuredDepModuleRefs,
 			includeDocsLink,
 		)
@@ -651,6 +665,14 @@ func readBufYAMLFile(
 			}
 			pluginConfigs = append(pluginConfigs, pluginConfig)
 		}
+		var policyConfigs []PolicyConfig
+		for _, externalPolicyConfig := range externalBufYAMLFile.Policies {
+			policyConfig, err := newPolicyConfigForExternalV2(externalPolicyConfig)
+			if err != nil {
+				return nil, err
+			}
+			policyConfigs = append(policyConfigs, policyConfig)
+		}
 		configuredDepModuleRefs, err := getConfiguredDepModuleRefsForExternalDeps(externalBufYAMLFile.Deps)
 		if err != nil {
 			return nil, err
@@ -662,6 +684,7 @@ func readBufYAMLFile(
 			topLevelLintConfig,
 			topLevelBreakingConfig,
 			pluginConfigs,
+			policyConfigs,
 			configuredDepModuleRefs,
 			includeDocsLink,
 		)
@@ -861,6 +884,16 @@ func writeBufYAMLFile(writer io.Writer, bufYAMLFile BufYAMLFile) error {
 		}
 		externalBufYAMLFile.Plugins = externalPlugins
 
+		var externalPolicies []externalBufYAMLFilePolicyV2
+		for _, policyConfig := range bufYAMLFile.PolicyConfigs() {
+			externalPolicy, err := newExternalV2ForPolicyConfig(policyConfig)
+			if err != nil {
+				return syserror.Wrap(err)
+			}
+			externalPolicies = append(externalPolicies, externalPolicy)
+		}
+		externalBufYAMLFile.Policies = externalPolicies
+
 		data, err := encoding.MarshalYAML(&externalBufYAMLFile)
 		if err != nil {
 			return err
@@ -1272,6 +1305,7 @@ type externalBufYAMLFileV2 struct {
 	Lint     externalBufYAMLFileLintV2              `json:"lint,omitempty" yaml:"lint,omitempty"`
 	Breaking externalBufYAMLFileBreakingV1Beta1V1V2 `json:"breaking,omitempty" yaml:"breaking,omitempty"`
 	Plugins  []externalBufYAMLFilePluginV2          `json:"plugins,omitempty" yaml:"plugins,omitempty"`
+	Policies []externalBufYAMLFilePolicyV2          `json:"policies,omitempty" yaml:"policies,omitempty"`
 }
 
 // externalBufYAMLFileModuleV2 represents a single module configuration within a v2 buf.yaml file.
@@ -1302,7 +1336,7 @@ type externalBufYAMLFileLintV1Beta1V1 struct {
 	Except []string `json:"except,omitempty" yaml:"except,omitempty"`
 	// Ignore are the paths to ignore.
 	Ignore []string `json:"ignore,omitempty" yaml:"ignore,omitempty"`
-	/// IgnoreOnly are the ID/category to paths to ignore.
+	// IgnoreOnly are the ID/category to paths to ignore.
 	IgnoreOnly                           map[string][]string `json:"ignore_only,omitempty" yaml:"ignore_only,omitempty"`
 	EnumZeroValueSuffix                  string              `json:"enum_zero_value_suffix,omitempty" yaml:"enum_zero_value_suffix,omitempty"`
 	RPCAllowSameRequestResponse          bool                `json:"rpc_allow_same_request_response,omitempty" yaml:"rpc_allow_same_request_response,omitempty"`
@@ -1389,12 +1423,21 @@ func (eb externalBufYAMLFileBreakingV1Beta1V1V2) isEmpty() bool {
 		!eb.DisableBuiltin
 }
 
-// externalBufYAMLFilePluginV2 represents a single plugin config in a v2 buf.gyaml file.
+// externalBufYAMLFilePluginV2 represents a single plugin config in a v2 buf.yaml file.
 type externalBufYAMLFilePluginV2 struct {
 	Plugin  any            `json:"plugin,omitempty" yaml:"plugin,omitempty"`
 	Options map[string]any `json:"options,omitempty" yaml:"options,omitempty"`
 }
 
+// externalBufYAMLFilePolicyV2 represents a single policy config in a v2 buf.yaml file.
+type externalBufYAMLFilePolicyV2 struct {
+	Policy string `json:"policy,omitempty" yaml:"policy,omitempty"`
+	// Ignore are the paths to ignore.
+	Ignore []string `json:"ignore,omitempty" yaml:"ignore,omitempty"`
+	// IgnoreOnly are the ID/category to paths to ignore.
+	IgnoreOnly map[string][]string `json:"ignore_only,omitempty" yaml:"ignore_only,omitempty"`
+}
+
 func getZeroOrSingleValueForMap[K comparable, V any](m map[K]V) (V, error) {
 	var zero V
 	if len(m) > 1 {

private/bufpkg/bufconfig/buf_yaml_file_test.go

@@ -478,6 +478,31 @@ modules:
     excludes:
       - proto/bar
       - proto/foo
+`,
+	)
+	testReadWriteBufYAMLFileRoundTrip(
+		t,
+		// input
+		`version: v2
+policies:
+  - policy: buf.policy.yaml
+  - policy: buf.build/org/policy2:v1
+    ignore:
+      - foo/bar.proto
+    ignore_only:
+      ENUM_PASCAL_CASE:
+        - foo/foo.proto
+`,
+		// expected output
+		`version: v2
+policies:
+  - policy: buf.policy.yaml
+  - policy: buf.build/org/policy2:v1
+    ignore:
+      - foo/bar.proto
+    ignore_only:
+      ENUM_PASCAL_CASE:
+        - foo/foo.proto
 `,
 	)
 }

private/bufpkg/bufconfig/file.go

@@ -151,7 +151,7 @@ func readFile[F File](
 		var f F
 		return f, err
 	}
-	f, err := readFileFunc(data, nil, true)
+	f, err := readFileFunc(data, newObjectData(fileName, data), true)
 	if err != nil {
 		return f, newDecodeError(fileName, err)
 	}

private/bufpkg/bufconfig/object_data.go

@@ -40,6 +40,11 @@ type ObjectData interface {
 	isObjectData()
 }
 
+// NewObjectData returns a new ObjectData.
+func NewObjectData(name string, data []byte) ObjectData {
+	return newObjectData(name, data)
+}
+
 // GetBufYAMLV1Beta1OrV1ObjectDataForPrefix is a helper function that gets the ObjectData for the buf.yaml file at
 // the given bucket prefix, if the buf.yaml file was v1beta1 or v1.
 //

private/bufpkg/bufconfig/policy_config.go

@@ -0,0 +1,126 @@
+// Copyright 2020-2025 Buf Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package bufconfig
+
+import (
+	"errors"
+	"slices"
+
+	"github.com/bufbuild/buf/private/pkg/slicesext"
+	"github.com/bufbuild/buf/private/pkg/syserror"
+)
+
+// PluginConfig is a configuration for a policy.
+type PolicyConfig interface {
+	// Name returns the policy name. This is never empty.
+	Name() string
+	// Paths are specific to the Module. Users cannot ignore paths outside of their modules for check
+	// configs, which includes any imports from outside of the module.
+	// Paths are relative to roots.
+	// Paths are sorted.
+	IgnorePaths() []string
+	// Paths are specific to the Module. Users cannot ignore paths outside of their modules for
+	// check configs, which includes any imports from outside of the module.
+	// Paths are relative to roots.
+	// Paths are sorted.
+	IgnoreIDOrCategoryToPaths() map[string][]string
+
+	isPolicyConfig()
+}
+
+// NewPolicyConfig returns a new PolicyConfig.
+func NewPolicyConfig(
+	name string,
+	ignore []string,
+	ignoreOnly map[string][]string,
+) (PolicyConfig, error) {
+	return newPolicyConfig(name, ignore, ignoreOnly)
+}
+
+// *** PRIVATE ***
+
+type policyConfig struct {
+	name       string
+	ignore     []string
+	ignoreOnly map[string][]string
+}
+
+func newPolicyConfigForExternalV2(
+	externalConfig externalBufYAMLFilePolicyV2,
+) (*policyConfig, error) {
+	return newPolicyConfig(
+		externalConfig.Policy,
+		externalConfig.Ignore,
+		externalConfig.IgnoreOnly,
+	)
+}
+
+func newPolicyConfig(
+	name string,
+	ignore []string,
+	ignoreOnly map[string][]string,
+) (*policyConfig, error) {
+	if name == "" {
+		return nil, errors.New("must specify a name to the policy")
+	}
+	ignore = slicesext.ToUniqueSorted(ignore)
+	ignore, err := normalizeAndCheckPaths(ignore, "ignore")
+	if err != nil {
+		return nil, err
+	}
+	newIgnoreOnly := make(map[string][]string, len(ignoreOnly))
+	for k, v := range ignoreOnly {
+		v = slicesext.ToUniqueSorted(v)
+		v, err := normalizeAndCheckPaths(v, "ignore_only path")
+		if err != nil {
+			return nil, err
+		}
+		newIgnoreOnly[k] = v
+	}
+	ignoreOnly = newIgnoreOnly
+	return &policyConfig{
+		name:       name,
+		ignore:     ignore,
+		ignoreOnly: ignoreOnly,
+	}, nil
+}
+
+func (p *policyConfig) Name() string {
+	return p.name
+}
+
+func (p *policyConfig) IgnorePaths() []string {
+	return slices.Clone(p.ignore)
+}
+
+func (p *policyConfig) IgnoreIDOrCategoryToPaths() map[string][]string {
+	return copyStringToStringSliceMap(p.ignoreOnly)
+}
+
+func (p *policyConfig) isPolicyConfig() {}
+
+func newExternalV2ForPolicyConfig(
+	config PolicyConfig,
+) (externalBufYAMLFilePolicyV2, error) {
+	pluginConfig, ok := config.(*policyConfig)
+	if !ok {
+		return externalBufYAMLFilePolicyV2{}, syserror.Newf("unknown implementation of PolicyConfig: %T", pluginConfig)
+	}
+	return externalBufYAMLFilePolicyV2{
+		Policy:     pluginConfig.Name(),
+		Ignore:     slices.Clone(pluginConfig.IgnorePaths()),
+		IgnoreOnly: copyStringToStringSliceMap(pluginConfig.IgnoreIDOrCategoryToPaths()),
+	}, nil
+}